Port-out Quickstart Guide

When a carrier receives a port-in request they will send the current carrier a port-out notification to let them know that they wish to port-out a number, usually with the authorization of the end-user.

When Telnyx receives notice from another carrier for a port-out request, Telnyx will automatically create a port-out order in your account.

We typically ask that you respond to our port-out notification within 24 or 48 hours via email. If you do not wish for the numbers to be ported-out, it is important that you notify us as soon as possible in order to prevent the port-out from being processed. If you do not respond within that 24 or 48 hour window, we are required to authorize the port-out order.

First, you need to review your port-out orders to verify that they are valid and all information provided is correct.

To do so, you can list all port-out orders using the GET https://api.telnyx.com/v2/portouts request (API reference here) to find the order you are looking for. You can include a filter[status]=pending flag to narrow down the search results. See example request below.

curl --location -g --request GET 'https://api.telnyx.com/v2/portouts?filter[status]=pending' \
--header 'Authorization: Bearer [REDACTED]'

{
    "data": [
        {
            "already_ported": false,
            "authorized_name": null,
            "carrier_name": "{{winning_carrier}}",
            "city": null,
            "created_at": "2022-04-26T15:50:15+00:00",
            "current_carrier": "telnyx",
            "end_user_name": null,
            "foc_date": null,
            "id": "ab06d54a-bc1a-43b4-b448-82873f05fe32",
            "inserted_at": "2022-04-26T15:50:15+00:00",
            "lsr": [],
            "phone_numbers": [
                "{{e.164 phone number}}"
            ],
            "pon": null,
            "reason": null,
            "record_type": "portout",
            "requested_foc_date": "2022-04-29T00:00:00+00:00",
            "service_address": null,
            "spid": "{{winning_spid}}",
            "state": null,
            "status": "pending",
            "support_key": "PO_05fe32",
            "updated_at": "2022-04-26T15:50:32+00:00",
            "user_id": "40d68ba2-0847-4df2-be9c-b0e0cb673e75",
            "vendor": null,
            "zip": null
        }
    ],
    "meta": {
        "page_number": 1,
        "page_size": 20,
        "total_pages": 1,
        "total_results": 1
    }
}

If you already know the port-out order ID, you can use the GET https://api.telnyx.com/v2/portouts/:id endpoint (API reference here) to retrieve the order directly:

Request:

curl --location --request GET 'https://api.telnyx.com/v2/portouts/{{id}}' \
--header 'Authorization: Bearer [REDACTED]'


Response:

{
    "data": {
        "already_ported": false,
        "authorized_name": null,
        "carrier_name": "{{winning_carrier}}",
        "city": null,
        "created_at": "2022-04-26T15:50:15+00:00",
        "current_carrier": "telnyx",
        "end_user_name": null,
        "foc_date": null,
        "id": "ab06d54a-bc1a-43b4-b448-82873f05fe32",
        "inserted_at": "2022-04-26T15:50:15+00:00",
        "lsr": [],
        "phone_numbers": [
            "{{e.164 phone number}}"
        ],
        "pon": null,
        "reason": null,
        "record_type": "portout",
        "requested_foc_date": "2022-04-29T00:00:00+00:00",
        "service_address": null,
        "spid": "{{winning_spid}}",
        "state": null,
        "status": "pending",
        "support_key": "PO_05fe32",
        "updated_at": "2022-04-26T15:50:32+00:00",
        "user_id": "40d68ba2-0847-4df2-be9c-b0e0cb673e75",
        "vendor": null,
        "zip": null
    }
}

After reviewing the port-out order, you need to either authorize or reject the port-out.

To authorize the port-out, make a PATCH https://api.telnyx.com/v2/portouts/:id/authorized request (API reference here), where {id} is the port-out order ID.

Request:

curl --location --request PATCH 'https://api.telnyx.com/v2/portouts/{{id}}/authorized' \
--header 'Authorization: Bearer [REDACTED]'


Response:

{
    "data": {
        "already_ported": false,
        "authorized_name": null,
        "carrier_name": "{{winning_carrier}}",
        "city": null,
        "created_at": "2022-04-26T15:50:15+00:00",
        "current_carrier": "telnyx",
        "end_user_name": null,
        "foc_date": "2022-04-29T00:00:00+00:00",
        "id": "ab06d54a-bc1a-43b4-b448-82873f05fe32",
        "inserted_at": "2022-04-26T15:50:15+00:00",
        "lsr": [],
        "phone_numbers": [
            "{{e.164 phone number}}"
        ],
        "pon": null,
        "reason": null,
        "record_type": "portout",
        "requested_foc_date": "2022-04-29T00:00:00+00:00",
        "service_address": null,
        "spid": "{{winning_spid}}",
        "state": null,
        "status": "authorized",
        "support_key": "PO_05fe32",
        "updated_at": "2022-04-26T17:38:33+00:00",
        "user_id": "40d68ba2-0847-4df2-be9c-b0e0cb673e75",
        "vendor": null,
        "zip": null
    }
}

Once authorized, the phone numbers are cleared to port-out on the FOC date.

To reject a port-out order, first lookup the applicable rejection codes for your port out order using the GET https://api.telnyx.com/v2/portouts/rejections/:portout_id endpoint (API reference here). These are the possible reasons you can provide to reject your port-out order. The rejection codes will vary depending on the phone number(s) porting out. See example request below.

Request:
curl --location --request GET 'https://api.telnyx.com/v2/portouts/rejections/{{id}}' \
--header 'Authorization: ••••••'

Response:
{
    "data": [
        {
            "code": 1008,
            "description": "All Data Mismatch",
            "reason_required": false
        },
        {
            "code": 1006,
            "description": "Unauthorized Contact or Customer Signature",
            "reason_required": false
        },
        {
            "code": 1004,
            "description": "Customer Name Mismatch",
            "reason_required": false
        },
        {
            "code": 1002,
            "description": "Address Mismatch",
            "reason_required": false
        },
        {
            "code": 1001,
            "description": "Other",
            "reason_required": true
        }
    ]
}

Once you identify the appropriate rejection code for your order, perform a PATCH https://api.telnyx.com/v2/portouts/{{id}}/rejected-pending request (API reference here). And include the rejection code in the body of the request. See example request below.

Request:
curl --location --request PATCH 'https://api.telnyx.com/v2/portouts/{{id}}/rejected-pending' \
--header 'Content-Type: application/json' \
--header 'Authorization: ••••••' \
--data '{
"rejection_code": 1008
}'

Response:
{
    "data": {
        "id": "89bda5da-c74e-4ce1-b9b2-f89ad8d26bd4",
        "reason": null,
        "status": "rejected-pending",
        "state": null,
        "zip": null,
        "record_type": "portout",
        "inserted_at": "2024-10-23T19:22:36+00:00",
        "updated_at": "2024-10-23T19:38:52+00:00",
        "city": null,
        "user_id": "c6b8da5d-0b1a-48fc-965d-91f96a34c847",
        "spid": "{winning_spid}}",
        "foc_date": null,
        "phone_numbers": [
            "{{e.164_phone_number}}"
        ],
        "requested_foc_date": "2024-10-30T00:00:00+00:00",
        "carrier_name": "{{winning_carrier}}",
        "pon": null,
        "support_key": "PO_d26bd4",
        "created_at": "2024-10-23T19:22:36+00:00",
        "end_user_name": "Test",
        "vendor": null,
        "already_ported": false,
        "authorized_name": "Test",
        "service_address": null,
        "current_carrier": "telnyx",
        "lsr": [],
        "pin_validation_eligible": true,
        "rejection_code": 1008,
        "validate_pin": false
    }
}

The rejection code 1001 "Other" is eligible for some port-out orders. When you use this code, you will need to provide an additional reason in the body of the API request explaining why you are rejecting the order. See an example request below:

Request:
curl --location --request PATCH 'https://api.telnyx.com/v2/portouts/{{id}}/rejected-pending' \
--header 'Content-Type: application/json' \
--header 'Authorization: ••••••' \
--data '{
"rejection_code": 1001,
"reason": "this is an invalid port out request"
}'

Response:
{
    "data": {
        "id": "89bda5da-c74e-4ce1-b9b2-f89ad8d26bd4",
        "reason": "this is an invalid port out request",
        "status": "rejected-pending",
        "state": null,
        "zip": null,
        "record_type": "portout",
        "inserted_at": "2024-10-23T19:22:36+00:00",
        "updated_at": "2024-10-23T19:42:34+00:00",
        "city": null,
        "user_id": "c6b8da5d-0b1a-48fc-965d-91f96a34c847",
        "spid": "{{winning_spid}}",
        "foc_date": null,
        "phone_numbers": [
            "{{e.164_phone_number}}"
        ],
        "requested_foc_date": "2024-10-30T00:00:00+00:00",
        "carrier_name": "{{winning_carrier}}",
        "pon": null,
        "support_key": "PO_d26bd4",
        "created_at": "2024-10-23T19:22:36+00:00",
        "end_user_name": "Test",
        "vendor": null,
        "already_ported": false,
        "authorized_name": "Test",
        "service_address": null,
        "current_carrier": "telnyx",
        "lsr": [],
        "pin_validation_eligible": true,
        "rejection_code": 1001,
        "validate_pin": false
    }
}

If rejected, Porting Ops will review the reasoning to determine whether the port-out Order needs to be updated, or whether the port-out order can be canceled.

---

If the port-out request is neither approved or rejected within 48 hours it will automatically receive FOC for the requested porting date.