---
title: "Create a porting order"
method: POST
path: "/porting_orders"
tags: ["Porting Orders"]
---

# Create a porting order

`POST /porting_orders`

Creates a new porting order object.

## Request body

- CreatePortingOrder
  - `phone_numbers` string[], required — The list of +E.164 formatted phone numbers
  - `customer_reference` string, nullable — A customer-specified reference number for customer bookkeeping purposes
  - `customer_group_reference` string — A customer-specified group reference for customer bookkeeping purposes

## Response `201`

Successful response

- object
  - `data` PortingOrder[]
    - `id` string, uuid — Uniquely identifies this porting order
    - `customer_reference` string, nullable — A customer-specified reference number for customer bookkeeping purposes
    - `customer_group_reference` string, nullable — A customer-specified group reference for customer bookkeeping purposes
    - `created_at` string, date-time — ISO 8601 formatted date indicating when the resource was created.
    - `updated_at` string, date-time — ISO 8601 formatted date indicating when the resource was created.
    - `status` PortingOrderStatus — Porting order status
      - `details` PortingOrdersExceptionType[] — A list of 0 or more details about this porting order's status
        - `code` 'ACCOUNT_NUMBER_MISMATCH' | 'AUTH_PERSON_MISMATCH' | 'BTN_ATN_MISMATCH' | 'ENTITY_NAME_MISMATCH' | 'FOC_EXPIRED' | 'FOC_REJECTED' | 'LOCATION_MISMATCH' | 'LSR_PENDING' | 'MAIN_BTN_PORTING' | 'OSP_IRRESPONSIVE' | 'OTHER' | 'PASSCODE_PIN_INVALID' | 'PHONE_NUMBER_HAS_SPECIAL_FEATURE' | 'PHONE_NUMBER_MISMATCH' | 'PHONE_NUMBER_NOT_PORTABLE' | 'PORT_TYPE_INCORRECT' | 'PORTING_ORDER_SPLIT_REQUIRED' | 'POSTAL_CODE_MISMATCH' | 'RATE_CENTER_NOT_PORTABLE' | 'SV_CONFLICT' | 'SV_UNKNOWN_FAILURE' — Identifier of an exception type
        - `description` string — Description of an exception type
      - `value` 'draft' | 'in-process' | 'submitted' | 'exception' | 'foc-date-confirmed' | 'ported' | 'cancelled' | 'cancel-pending' — The current status of the porting order
    - `support_key` string, nullable — A key to reference this porting order when contacting Telnyx customer support. This information is not available in draft porting orders.
    - `parent_support_key` string, nullable — A key to reference for the porting order group when contacting Telnyx customer support. This information is not available for porting orders in `draft` state
    - `porting_phone_numbers_count` integer — Count of phone numbers associated with this porting order
    - `old_service_provider_ocn` string — Identifies the old service provider
    - `phone_numbers` PortingPhoneNumber[] — List of phone numbers associated with this porting order
      - `porting_order_status` 'draft' | 'in-process' | 'submitted' | 'exception' | 'foc-date-confirmed' | 'cancel-pending' | 'ported' | 'cancelled' — The current status of the porting order
      - `phone_number_type` 'landline' | 'local' | 'mobile' | 'national' | 'shared_cost' | 'toll_free' — The type of the phone number
      - `phone_number` string — E164 formatted phone number
      - `porting_order_id` string, uuid — Identifies the associated port request
      - `support_key` string — A key to reference this porting order when contacting Telnyx customer support
      - `activation_status` 'New' | 'Pending' | 'Conflict' | 'Cancel Pending' | 'Failed' | 'Concurred' | 'Activate RDY' | 'Disconnect Pending' | 'Concurrence Sent' | 'Old' | 'Sending' | 'Active' | 'Cancelled' — Activation status
      - `portability_status` 'pending' | 'confirmed' | 'provisional' — Specifies whether Telnyx is able to confirm portability this number in the United States & Canada. International phone numbers are provisional by default.
      - `requirements_status` 'requirement-info-pending' | 'requirement-info-under-review' | 'requirement-info-exception' | 'approved' — The current status of the requirements in a INTL porting order
      - `record_type` string — Identifies the type of the resource.
    - `documents` PortingOrderDocuments — Can be specified directly or via the `requirement_group_id` parameter.
      - `loa` string, uuid, nullable — Returned ID of the submitted LOA via the Documents endpoint
      - `invoice` string, uuid, nullable — Returned ID of the submitted Invoice via the Documents endpoint
    - `misc` PortingOrderMisc
      - `type` 'full' | 'partial' — A port can be either 'full' or 'partial'. When type is 'full' the other attributes should be omitted.
      - `remaining_numbers_action` 'keep' | 'disconnect' | 'null', nullable — Remaining numbers can be either kept with their current service provider or disconnected. 'new_billing_telephone_number' is required when 'remaining_numbers_action' is 'keep'.
      - `new_billing_phone_number` string, nullable — New billing phone number for the remaining numbers. Used in case the current billing phone number is being ported to Telnyx. This will be set on your account with your current service provider and should be one of the numbers remaining on that account.
    - `end_user` PortingOrderEndUser
      - `admin` PortingOrderEndUserAdmin
        - `entity_name` string, nullable — Person Name or Company name requesting the port
        - `auth_person_name` string, nullable — Name of person authorizing the porting order
        - `billing_phone_number` string, nullable — Billing phone number associated with these phone numbers
        - `account_number` string, nullable — The authorized person's account number with the current service provider
        - `tax_identifier` string, nullable — European tax identification number. Applicable only in the European Union
        - `pin_passcode` string, nullable — PIN/passcode possibly required by the old service provider for extra verification
        - `business_identifier` string, nullable — European business identification number. Applicable only in the European Union
      - `location` PortingOrderEndUserLocation
        - `street_address` string, nullable — First line of billing address
        - `extended_address` string, nullable — Second line of billing address
        - `locality` string, nullable — City or municipality of billing address
        - `administrative_area` string, nullable — State, province, or similar of billing address
        - `postal_code` string, nullable — Postal Code of billing address
        - `country_code` string, nullable — ISO3166-1 alpha-2 country code of billing address
    - `activation_settings` PortingOrderActivationSettings
      - `foc_datetime_requested` string, date-time, nullable — ISO 8601 formatted Date/Time requested for the FOC date
      - `foc_datetime_actual` string, date-time, nullable — ISO 8601 formatted Date/Time of the FOC date
      - `fast_port_eligible` boolean — Indicates whether this porting order is eligible for FastPort
      - `activation_status` 'New' | 'Pending' | 'Conflict' | 'Cancel Pending' | 'Failed' | 'Concurred' | 'Activate RDY' | 'Disconnect Pending' | 'Concurrence Sent' | 'Old' | 'Sending' | 'Active' | 'Cancelled' — Activation status
    - `phone_number_configuration` PortingOrderPhoneNumberConfiguration
      - `billing_group_id` string, nullable — identifies the billing group to set on the numbers when ported
      - `connection_id` string, nullable — identifies the connection to set on the numbers when ported
      - `messaging_profile_id` string, nullable — identifies the messaging profile to set on the numbers when ported
      - `emergency_address_id` string, nullable — identifies the emergency address to set on the numbers when ported
      - `tags` string[]
    - `phone_number_type` 'landline' | 'local' | 'mobile' | 'national' | 'shared_cost' | 'toll_free' — The type of the phone number
    - `description` string — A description of the porting order
    - `requirements` PortingOrderRequirement[] — List of documentation requirements for porting numbers. Can be set directly or via the `requirement_group_id` parameter.
      - `field_type` 'document' — Type of value expected on field_value field
      - `field_value` string — identifies the document that satisfies this requirement
      - `requirement_type_id` string — Identifies the requirement type that meets this requirement
      - `record_type` string — Identifies the type of the resource.
    - `requirements_met` boolean — Is true when the required documentation is met
    - `user_feedback` PortingOrderUserFeedback
      - `user_rating` integer, nullable — Once an order is ported, cancellation is requested or the request is cancelled, the user may rate their experience
      - `user_comment` string, nullable — A comment related to the customer rating.
    - `user_id` string, uuid — Identifies the user (or organization) who requested the porting order
    - `webhook_url` string, uri, nullable
    - `record_type` string — Identifies the type of the resource.
    - `messaging` PortingOrderMessaging — Information about messaging porting process.
      - `messaging_capable` boolean — Indicates whether the porting order can also port messaging capabilities.
      - `enable_messaging` boolean — Indicates whether Telnyx will port messaging capabilities from the losing carrier. If false, any messaging capabilities will stay with their current provider.
      - `messaging_port_status` 'not_applicable' | 'pending' | 'activating' | 'exception' | 'canceled' | 'partial_port_complete' | 'ported' — The current status of the messaging porting.
      - `messaging_port_completed` boolean — Indicates whether the messaging porting has been completed.
    - `additional_steps` string[] — For specific porting orders, we may require additional steps to be taken before submitting the porting order.

## Other responses

- `401` — Unauthorized
- `422` — Unprocessable entity. Check message field in response for details.

---

[API](https://skmtc.net/team-telnyx/apis/telnyx-api-2.md) · [All operations](https://skmtc.net/team-telnyx/apis/telnyx-api-2/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/team-telnyx/telnyx-api-2/versions/8f5f4e537994/schema)