Port-in Quickstart Guide

Workflow steps:

In this quickstart, you'll learn how to create and submit a port request using Porting V2 API commands. Just follow these simple steps:

Check portability of your telephone numbers
Create a draft Porting Order
View allowable FOC dates
Submit relevant supporting documents
Update your Porting Order
Confirm and submit your Porting Order

Step 1: Check portability

First, use the following command to check whether your numbers are portable into Telnyx.

Note
Don't forget to update YOUR_API_KEY here.

curl --location --request POST 'https://api.telnyx.com/v2/portability_checks' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--data-raw '{
    "phone_numbers": [
        "+13125552486",
        "+12125558724"
    ]
}'

{
    "data": [
        {
            "carrier_name": "example_carrier",
            "fast_portable": true,
            "messaging_capable": true,
            "not_portable_reason": null,
            "phone_number": "+12125558724",
            "phone_number_type": "local",
            "portable": true,
            "record_type": "portability_check_result"
        },
        {
            "carrier_name": "",
            "fast_portable": false,
            "messaging_capable": false,
            "not_portable_reason": "no_coverage",
           "phone_number": "+13125552486",
            "phone_number_type": "local",
            "portable": false,
            "record_type": "portability_check_result"
        }
    ]
}

In the response, you will get back a list of portable and nonportable numbers. Proceeding to Step 2 with any nonportable numbers will result in 4xx errors.

Step 2: Create a draft porting order

Next, you can create your draft port order using the following command.

curl --location --request POST 'https://api.telnyx.com/v2/porting_orders' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer [REDACTED]' \
--data-raw '{
"phone_numbers": [
        "+16785554405"
    ]
}'

If you create a draft port order with multiple numbers, it is possible that the numbers will be split into multiple port orders. If this occurs, you will need to update and submit each draft port order individually. Numbers are split based on the following criteria:

Country
Number type
SPID (for US/CA numbers)
FastPort eligibility

Step 3: View allowable FOC dates

Using the following command, you will be able to see the allowed FOC dates for your port order. You will later be asked to submit one of these dates using the foc_datetime_requested field when completing your Porting Order.

curl --location --request GET 'https://api.telnyx.com/v2/porting_orders/d25fed86-1f15-4f29-a0c0-ec923b18ee46/allowed_foc_windows' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer [REDACTED]'

Step 4: Submit relevant supporting documents

At a minimum, you will need to attach a Letter of Authorization (LOA) and Invoice to your Porting Order. Before doing so, you first need to upload those documents and retrieve their document id.

You can easily upload your documents as a multipart, as shown below

curl --location --request POST 'https://api.telnyx.com/v2/documents' \
--header 'Content-Type: multipart/form-data' \
--header 'Authorization: Bearer [REDACTED]' \
--form 'file=@/Users/xd/Downloads/threads-bugs.pdf'

For more information about uploading documents, check out the Documents API

Step 5: Update your porting order

At this point, you should have all the necessary info you need to complete a Porting Order. To simplify things, we are going to break this down into two steps.

Part 1

First, you can update your Port Order with the required general information.

curl --location --request PATCH 'https://api.telnyx.com/v2/porting_orders/d25fed86-1f15-4f29-a0c0-ec923b18ee46' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer [REDACTED]' \
--data-raw '{
    "misc": {
        "type": "full",
        "remaining_numbers_action": null,
        "new_billing_phone_number": null
    },
    "end_user": {
        "admin": {
            "entity_name": "Telnyx",
            "auth_person_name": "John Doe",
            "billing_phone_number": "+1 I am not valid",
            "account_number": "1",
            "tax_identifier": "",
            "pin_passcode": "",
            "business_identifier": ""
        },
        "location": {
            "street_address": "311 W Superior St",
            "extended_address": "Suite 504",
            "locality": "Chicago",
            "administrative_area": "IL",
            "postal_code": "60654",
            "country_code": "US"
        }
    },
    "activation_settings": {
        "foc_datetime_requested": "2021-04-25T13:39:42Z"
    },
    "phone_number_configuration": {
        "connection_id": "",
        "message_profile_id": "",
        "emergency_address_id": "",
        "tags": [
            "culpa quis",
            "consectetur"
        ]
    },
    "webhook_url": "https://example.com/9c4ac3ce-43d8-4a3f-bcdc-2831747c7105",
    "user_reference": "test"
}'

Part 2

Second, you can attach those documents that you submitted earlier in Step 4

curl --location --request PATCH 'https://api.telnyx.com/v2/porting_orders/d25fed86-1f15-4f29-a0c0-ec923b18ee46' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer [REDACTED]' \
--data-raw '{
    "documents": {
        "loa": "64ffb720-04c7-455b-92d6-20fcca92e935",
        "invoice": "ce74b771-d23d-4960-81ec-8741b3862146"
    }
}'

If during either of these steps any fields you submit are invalid, the PATCH request will not be successful. In the example below, the API responds with 422.

Request:

curl --location --request PATCH 'https://api.telnyx.com/v2/porting_orders/e0fcd703-efec-48cb-b5ed-a6dbd56354e9' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer [REDACTED]' \
--data-raw '{
    "misc": {
        "type": "full",
        "remaining_numbers_action": null,
        "new_billing_phone_number": null
    },
    "end_user": {
        "admin": {
            "entity_name": "Telnyx",
            "auth_person_name": "X.D. Zhai",
            "billing_phone_number": "+1 I am not valid",
            "account_number": "1",
            "tax_identifier": "",
            "pin_passcode": "",
            "business_identifier": ""
        },
        "location": {
            "street_address": "311 W Superior St",
            "extended_address": "Suite 504",
            "locality": "Chicago",
            "administrative_area": "IL",
            "postal_code": "60654",
            "country_code": "US"
        }
    },
    "activation_settings": {
        "foc_datetime_requested": "2020-11-06T13:39:42Z"
    },
    "phone_number_configuration": {
        "connection_id": "",
        "message_profile_id": "",
        "emergency_address_id": "",
        "tags": [
            "culpa quis",
            "consectetur"
        ]
    },
    "documents": {
        "loa": "64ffb720-04c7-455b-92d6-20fcca92e935",
        "invoice": "ce74b771-d23d-4960-81ec-8741b3862146"
    },
    "user_feedback": {
        "user_rating": "",
        "user_comment": ""
    },
    "webhook_url": "https://example.com/4f141040-3bab-410b-8cec-9551a8195882",
    "customer_reference": "1-alpha-2-bravo-3-charlie"
}'

Response:

{
    "errors": [
        {
            "detail": "The 'billing_phone_number' parameter must be valid.",
            "source": {
                "pointer": "/billing_phone_number"
            },
            "title": "Invalid billing_phone_number"
        }
}

Step 6: Confirm and submit your porting order

If you are satisfied with your porting order, you can execute the command below to submit it. If successful, the porting order will transition from a "draft" status to an "in-process" status

curl --location --request POST 'https://api.telnyx.com/v2/porting_orders/d25fed86-1f15-4f29-a0c0-ec923b18ee46/actions/confirm' \
--header 'Authorization: Bearer [REDACTED]'

And that's it! You just successfully submitted a port request!