Skip to main content

Create a porting order

POST 
/porting_orders

Creates a new porting order object.

Request ​

Body

required

    phone_numbers string[]required

    The list of +E.164 formatted phone numbers

    customer_reference string

    A customer-specified reference number for customer bookkeeping purposes

Responses ​

201: Successful response

Schema

    data

    object[]

  • Array [

    • id uuid

    Uniquely identifies this porting order

    customer_reference string

    A customer-specified reference number for customer bookkeeping purposes

    created_at date-time

    ISO 8601 formatted date indicating when the resource was created.

    updated_at date-time

    ISO 8601 formatted date indicating when the resource was created.

    status

    object

    Porting order status

    details

    object[]

    A list of 0 or more details about this porting order's status

  • Array [

    • code string

    Possible values: [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

  • ]

    • A list of 0 or more details about this porting order's status

    value string

    Possible values: [draft, in-process, submitted, exception, foc-date-confirmed, ported, cancelled, cancel-pending]

    The current status of the porting order

    Porting order status

    support_key string

    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

    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

    documents

    object

    Can be specified directly or via the requirement_group_id parameter.

    loa uuid

    Returned ID of the submitted LOA via the Documents endpoint

    invoice uuid

    Returned ID of the submitted Invoice via the Documents endpoint

    misc

    object

    type PortingOrderType (string)

    Possible values: [full, partial]

    A port can be either 'full' or 'partial'. When type is 'full' the other attributes should be omitted.

    remaining_numbers_action string

    Possible values: [keep, disconnect]

    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

    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

    object

    admin

    object

    entity_name string

    Person Name or Company name requesting the port

    auth_person_name string

    Name of person authorizing the porting order

    billing_phone_number string

    Billing phone number associated with these phone numbers

    account_number string

    The authorized person's account number with the current service provider

    tax_identifier string

    European tax identification number. Applicable only in the European Union

    pin_passcode string

    PIN/passcode possibly required by the old service provider for extra verification

    business_identifier string

    European business identification number. Applicable only in the European Union

    location

    object

    street_address string

    First line of billing address

    extended_address string

    Second line of billing address

    locality string

    City or municipality of billing address

    administrative_area string

    State, province, or similar of billing address

    postal_code string

    Postal Code of billing address

    country_code string

    ISO3166-1 alpha-2 country code of billing address

    activation_settings

    object

    foc_datetime_requested date-time

    ISO 8601 formatted Date/Time requested for the FOC date

    foc_datetime_actual date-time

    ISO 8601 formatted Date/Time of the FOC date

    fast_port_eligible boolean

    Indicates whether this porting order is eligible for FastPort

    activation_status PortingOrderActivationStatus (string)

    Possible values: [New, Pending, Conflict, Cancel Pending, Failed, Concurred, Activate RDY, Disconnect Pending, Concurrence Sent, Old, Sending, Active, Cancelled]

    Activation status

    phone_number_configuration

    object

    billing_group_id string

    identifies the billing group to set on the numbers when ported

    connection_id string

    identifies the connection to set on the numbers when ported

    messaging_profile_id string

    identifies the messaging profile to set on the numbers when ported

    emergency_address_id string

    identifies the emergency address to set on the numbers when ported

    tags string[]
    phone_number_type string

    Possible values: [landline, local, mobile, national, shared_cost, toll_free]

    The type of the phone number

    description string

    A description of the porting order

    requirements

    object[]

    List of documentation requirements for porting numbers. Can be set directly or via the requirement_group_id parameter.

  • Array [

    • field_type string

    Possible values: [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

    object

    user_rating integer

    Once an order is ported, cancellation is requested or the request is cancelled, the user may rate their experience

    user_comment string

    A comment related to the customer rating.

    user_id uuid

    Identifies the user (or organization) who requested the porting order

    webhook_url uri
    record_type string

    Identifies the type of the resource.

    messaging

    object

    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 string

    Possible values: [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.

    Information about messaging porting process.

  • ]

401: Unauthorized

422: Unprocessable entity. Check message field in response for details.

Request samples

curl -L 'https://api.telnyx.com/v2/porting_orders' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <TOKEN>' \
-d '{
  "phone_numbers": [
    "+13035550000",
    "+13035550001",
    "+13035550002"
  ],
  "customer_reference": "Acct 123abc"
}'

Response samples

{
  "data": [
    {
      "activation_settings": {
        "activation_status": null,
        "fast_port_eligible": true,
        "foc_datetime_actual": null,
        "foc_datetime_requested": null
      },
      "created_at": "2022-03-17T18:01:01Z",
      "customer_reference": null,
      "description": "FP Telnyx",
      "documents": {
        "loa": null,
        "invoice": null
      },
      "end_user": {
        "admin": {
          "account_number": null,
          "auth_person_name": null,
          "billing_phone_number": null,
          "business_identifier": null,
          "entity_name": null,
          "pin_passcode": null,
          "tax_identifier": null
        },
        "location": {
          "administrative_area": null,
          "country_code": null,
          "extended_address": null,
          "locality": null,
          "postal_code": null,
          "street_address": null
        }
      },
      "id": "b0ea6d6f-de31-4079-a536-992e0c98b037",
      "misc": null,
      "old_service_provider_ocn": "Unreal Communications",
      "parent_support_key": null,
      "phone_number_configuration": {
        "billing_group_id": null,
        "connection_id": null,
        "emergency_address_id": null,
        "messaging_profile_id": null,
        "tags": []
      },
      "phone_number_type": "local",
      "phone_numbers": [
        {
          "activation_status": null,
          "phone_number": "{e.164 TN}",
          "phone_number_type": "local",
          "portability_status": "confirmed",
          "porting_order_id": "b0ea6d6f-de31-4079-a536-992e0c98b037",
          "porting_order_status": "draft",
          "record_type": "porting_phone_number",
          "requirements_status": "requirement-info-pending",
          "support_key": null
        }
      ],
      "porting_phone_numbers_count": 1,
      "record_type": "porting_order",
      "requirements": [],
      "requirements_met": false,
      "status": {
        "details": [],
        "value": "draft"
      },
      "support_key": null,
      "updated_at": "2022-03-17T18:01:01Z",
      "user_feedback": {
        "user_comment": null,
        "user_rating": null
      },
      "messaging": {
        "messaging_capable": true,
        "enable_messaging": false,
        "messaging_port_status": "not_applicable",
        "messaging_port_completed": false
      },
      "user_id": "40d68ba2-0847-4df2-be9c-b0e0cb673e75",
      "webhook_url": null
    }
  ]
}