Port In Extended Numbers

Phone number extensions allow multiple phone lines to branch off from a single direct inward dialing (DID) number or main line. This setup is particularly useful in environments like offices or call centers where individual desks or employees need to be reachable through their unique extensions.

The core component of this system is the “route” number (a.k.a. “main” number), which serves as the primary phone number for incoming calls. It acts as the gateway through which all incoming calls are accessed before being directed to specific extensions.

Extended numbers, on the other hand, are the unique identifiers assigned to different endpoints (like specific desks or employees) that branch off from the main route number. They are not full phone numbers by themselves but are short sequences of digits dialed after reaching the route number, allowing callers to bypass the main line and connect directly to the desired department or individual.

For example, let’s take the phone number +49 20 12345678. This is the “route” number. If I owned this number, I may add extensions to it, like +49 20 123456780 or +49 20 1234567806.

Note

: this is currently only available for German port orders.

First, create a porting order with the “route” number only.

While your order is in a draft, in-process, or exception status, you can add the extensions by using the POST v2/porting_orders/:porting_order_id/phone_number_extensions API request (api reference here).

You may have multiple phone numbers in your porting order. You must specify which phone number will have extensions attached by providing the porting_phone_number_id in the API request. To retrieve the appropriate porting_phone_number_id, use the GET v2/porting_phone_numbers request (api reference here).

See example request below:

Note

Don't forget to update YOUR_API_KEY here.

Request:

curl --location --request POST 'https://api.telnyx.com/v2/porting_orders/{{porting_order_id}}/phone_number_extensions' \
--header 'Content-Type: application/json' \
--header 'Authorization: YOUR_API_KEY' \
--data '{
    "porting_phone_number_id": "{{porting_phone_number_id}}",
    "extension_range": {
        "start_at": 0,
        "end_at": 9
    },
    "activation_ranges": [
        {
            "start_at": 0,
            "end_at": 9
        }
    ]
}'

Response:

{
    "data": {
        "id": "e7614221-d618-4205-b4fe-4fa59266b31b",
        "record_type": "porting_phone_number_extension",
        "updated_at": "2024-06-27T17:28:14.551521Z",
        "created_at": "2024-06-27T17:28:14.551521Z",
        "porting_phone_number_id": "{{porting_phone_number_id}}",
        "extension_range": {
            "start_at": 0,
            "end_at": 9
        },
        "activation_ranges": [
            {
                "start_at": 0,
                "end_at": 9
            }
        ]
    }
}

Extensions are typically created in blocks. For example, let's assume you had a route number +49 20 12345678 and wanted to activate the extension +49 20 123456784. To do so, the extension range +49 20 123456780 - +49 20 123456789 would be created. Within that range, extension +49 20 123456784 would be activated, while the rest of the extensions remained inactive.

The extension_range object represents the full range of extensions available for the route number. The extension_range will typically be either 10 phone numbers (0 - 9), 100 phone numbers (0 - 99), or possibly 1000 phone numbers (0 - 999). All extensions in the extension_range will port over with the route number.

The activation_ranges array lets you specify which extensions you want active immediately upon port completion. Any extension in the extension_range that is not in the activation_ranges array will port, but will remain inactive on your acccount.

Other considerations:

• The maximum possible extension_range and activation_ranges is between 0 and 999. i.e. entering 1000 as the end_at value would be considered invalid.
• The activation_ranges defined must be equal to or a subset of the extension_range. i.e. entering an extension_range between 0 - 10 and an activation_ranges between 0 - 100 would be considered invalid.
• The activation_ranges defined cannot overlap. i.e. you cannot enter the ranges 5 - 12 and 7 - 14.

Example 1: I am porting in +49 20 12345678 with extensions +49 20 123456785 and +49 20 123456786. My payload would include the following:

    "extension_range": {
        "start_at": 0,
        "end_at": 9
    },
    "activation_ranges": [
        {
            "start_at": 5,
            "end_at": 6
        }

Example 2: I am porting in +49 20 12345678 with extensions +49 20 1234567804, +49 20 1234567819, +49 20 1234567820, and +49 20 1234567842. My payload would include:

    "extension_range": {
        "start_at": 0,
        "end_at": 99
    },
    "activation_ranges": [
        {
            "start_at": 4,
            "end_at": 4
        },
        {
            "start_at": 19,
            "end_at": 20
        },
        {
            "start_at": 42,
            "end_at": 42
        }

The “route” number will be returned in the GET v2/porting_phone_numbers API request, but the extended numbers will not.

To view which extended numbers are included in your porting order, use the GET v2/porting_orders/:porting_order_id/phone_number_extensions API request (api reference here). See example request below:

Request:

curl --location --request GET 'https://api.telnyx.com/v2/porting_orders/{{porting_order_id}}/phone_number_extensions' \
--header 'Authorization: ••••••'

Response:

{
    "data": [
        {
            "id": "e7614221-d618-4205-b4fe-4fa59266b31b",
            "record_type": "porting_phone_number_extension",
            "updated_at": "2024-06-27T17:28:14.551521Z",
            "created_at": "2024-06-27T17:28:14.551521Z",
            "porting_phone_number_id": "{{porting_phone_number_id}}",
            "extension_range": {
                "start_at": 0,
                "end_at": 9
            },
            "activation_ranges": [
                {
                    "start_at": 0,
                    "end_at": 9
                }
            ]
        }
    ],
    "meta": {
        "page_size": 25,
        "page_number": 1,
        "total_pages": 1,
        "total_results": 1
    }
}

Mistakes happen.

You can remove the extended numbers from your porting order by performing a DELETE v2/porting_orders/:porting_order_id/phone_number_extensions/:id API request (API reference here). See example request below:

Request:

curl --location --request DELETE 'https://api.telnyx.com/v2/porting_orders/{{porting_order_id}}/phone_number_extensions/e7614221-d618-4205-b4fe-4fa59266b31b' \
--header 'Authorization: ••••••'

Response:
{
    "data": {
        "id": "e7614221-d618-4205-b4fe-4fa59266b31b",
        "record_type": "porting_phone_number_extension",
        "updated_at": "2024-06-27T17:28:14.551521Z",
        "created_at": "2024-06-27T17:28:14.551521Z",
        "porting_phone_number_id": "{{porting_phone_number_id}}",
        "extension_range": {
            "start_at": 0,
            "end_at": 9
        },
        "activation_ranges": [
            {
                "start_at": 0,
                "end_at": 9
            }
        ]
    }
}

The order should be under draft, in-process, or exception status to delete extended numbers.