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.
Request:
curl --location --request POST 'https://api.telnyx.com/v2/portability_checks' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer [REDACTED]' \
--data-raw '{
"phone_numbers": [
"+13125552486",
"+12125558724"
]
}'
Response:
{
"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"
}
]
}
Note: After pasting the above content, Kindly check and remove any new line added
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"
]
}'
Note: After pasting the above content, Kindly check and remove any new line added
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]'
Note: After pasting the above content, Kindly check and remove any new line added
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'
Note: After pasting the above content, Kindly check and remove any new line added
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"
}'
Note: After pasting the above content, Kindly check and remove any new line added
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"
}
}'
Note: After pasting the above content, Kindly check and remove any new line added
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"
}
}
Note: After pasting the above content, Kindly check and remove any new line added
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]'
Note: After pasting the above content, Kindly check and remove any new line added
And that's it! You just successfully submitted a port request!