Porting Blocks of Phone Numbers

Phone number blocks are groups of consecutive phone numbers assigned to a specific area or provider. Unlike individual phone numbers used by people or devices, blocks are managed in batches to organize and distribute phone resources efficiently across networks.

Note

: this is currently only available for German port orders.

1. More control over your port
2. Minimize exceptions
3. Phone number blocks are processed differently than individual phone numbers. They have unique rules when it comes to port outs and deletions. By indicating that you are porting in a block, it makes it easy for Telnyx to apply these unique processes/rules to your phone numbers.

To create a port order for your number block, use the POST https://api.telnyx.com/v2/porting_orders API request (API reference here) and specify the block in the payload. See an example request below:

Note

Don't forget to update YOUR_API_KEY here.

curl --location --request POST 'https://api.telnyx.com/v2/porting_orders' \
--header 'Content-Type: application/json' \
--header 'Authorization: YOUR_API_KEY' \
--data '{
    "phone_number_blocks": [
        {
            "phone_number_range": {
                "start_at": "+4920123456000",
                "end_at": "+4920123456099"
            },
            "activation_ranges": [
                {
                    "start_at": "+4920123456000",
                    "end_at": "+4920123456099"
                }
            ]
        }
    ]
}'

Let’s say you own a 1000 number block. In some countries, partial porting is not allowed. Even if some of those numbers are inactive, you are still required to submit a port request for the entire block.

The phone_number_range object represents the full number block that is porting in. of extensions available for the route number. The phone_number_range will typically be either 10 phone numbers (1 - 10), 100 phone numbers (1 - 100), or 1000 phone numbers (1 - 1000). All extensions in the phone_number_range will port, and must all be included in the LOA.

The activation_ranges array lets you specify which phone numbers within the block that you want active immediately upon port completion. Any phone number in the phone_number_range that is not in the activation_ranges array will port, but will remain inactive on your account.

Other considerations:

• The maximum size for a single block is 1000 phone numbers (0 - 999).
• The activation_ranges defined must be equal to or a subset of the phone_number_range. i.e. entering an phone_number_range between +4920123456000 - +4920123456010 and an activation_ranges between +4920123456000 - +4920123456100 would be considered invalid.
• The activation_ranges defined cannot overlap. i.e. you cannot enter the ranges +4920123456005 - +4920123456012 and +4920123456007 - +4920123456014.

Example 1: I am porting in my number block +4920123456000 - +4920123456999. However, I only want the phone numbers +4920123456000 - +4920123456775 active upon port completion. The remaining numbers will port, but I do not want them active on my account. In this scenario, my payload would include the following:

    "phone_number_blocks": [
        {
            "phone_number_range": {
                "start_at": "+4920123456000"
                "end_at": "+4920123456999"
            },
            "activation_ranges": [
                {
                    "start_at": "+4920123456000",
                    "end_at": "+4920123456775"
                }
            ]

Example 2: I am porting in my number block +4920123456000 - +4920123456099. However, I only want the phone numbers +4920123456000 - +4920123456064, and +4920123456087 active upon port completion. The remaining numbers will port, but I do not want them active on my account. In this scenario, my payload would include the following:

    "phone_number_blocks": [
        {
            "phone_number_range": {
                "start_at": "+4920123456000"
                "end_at": "+4920123456099"
            },
            "activation_ranges": [
                {
                    "start_at": "+4920123456000",
                    "end_at": "+4920123456064"
                },
                {
                    "start_at": "+4920123456087",
                    "end_at": "+4920123456087"
                }
            ]

Let's assume that you create and submit a port order for a few individual phone numbers (+4920123456007, +4920123456045, and +4920123456087. That order is eventually rejected. With the rejection reason being that those seemingly “individual” phone numbers are actually part of a block (+4920123456000 - +4920123456099), and the entire block needs to be ported.

In this case, the porting order you created would be missing phone numbers.

Rather than canceling your port order and creating a new one from scratch, you can update your porting order to add the remaining block with a POST https://api.telnyx.com/v2/porting_orders/:porting_order_id/phone_number_blocks API request (API reference here). See an example request below.

curl --location --request POST 'https://api.telnyx.com/v2/porting_orders/{{porting_order_id}}/phone_number_blocks' \
--header 'Content-Type: application/json' \
--header 'Authorization: ••••••' \
--data '{
  "phone_number_range": {
    "start_at": "+4920123456000",
    "end_at": "+4920123456099"
  },
  "activation_ranges": [
    {
    "start_at": "+4920123456000",
    "end_at": "+4920123456099"
    }
  ]
}'

Any phone number that was previously absent will be added to the order.

Other considerations:

• The order should be under draft, in-process, or exception status to add a block to your order.
• If you are adding a block to the port order, it must be the same country and phone number type. I.e. if you had a DE local port order, you could not add a PT toll_free block to that order. You could only add a DE local block to that order.

To view the blocks associated to your porting order (if any), you can perform a GET https://api.telnyx.com/v2/porting_orders/:porting_order_id/phone_number_blocks API request (API reference here). Sample request below:

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

Response:
{
    "data": [
        {
            "id": "58c49e27-8de6-47e4-bfe5-e4ecf0e94d46",
            "record_type": "porting_phone_number_block",
            "updated_at": "2024-06-27T20:05:18.240033Z",
            "country_code": "DE",
            "porting_order_id": "{{porting_order_id}}",
            "phone_number_type": "local",
            "created_at": "2024-06-27T20:05:18.240033Z",
            "phone_number_range": {
                "start_at": "+4920123456000",
                "end_at": "+4920123456099"
            },
            "activation_ranges": [
                {
                    "start_at": "+4920123456000",
                    "end_at": "+4920123456099"
                }
            ]
        }
    ],
    "meta": {
        "page_size": 25,
        "page_number": 1,
        "total_pages": 1,
        "total_results": 1
    }
}

When a block is created, it will have its own unique id. If you query the list porting phone numbers endpoint (API reference here), the block id will be present in the block_reference_id attribute. See sample request below.

Request:
curl --location --globoff --request GET 'https://api.telnyx.com/v2/porting_phone_numbers?filter[porting_order_id][eq]={{porting_order_id}}' \
--header 'Authorization: ••••••'

Response:
{
    "data": [
        {
            "id": "957df557-98f4-40da-a2e8-b412430cb512",
            "activate": true,
            "record_type": "porting_phone_number",
            "phone_number": "+4920123456000",
            "support_key": null,
            "porting_order_id": "{{porting_order_id}}",
            "portability_status": null,
            "phone_number_type": "local",
            "messaging_port_status": null,
            "block_reference_id": "58c49e27-8de6-47e4-bfe5-e4ecf0e94d46",
            "activation_status": null,
            "requirements_status": "requirement-info-pending",
            "porting_order_status": "draft"
        },
…

To remove a number block from a porting order, perform a DELETE https://api.telnyx.com/v2/porting_orders/:porting_order_id/phone_number_blocks/:id API request (API reference here). Include the id of the number block in the url path. See example request below:

Request:
curl --location --request DELETE 'https://api.telnyx.com/v2/porting_orders/{{porting_order_id}}/phone_number_blocks/58c49e27-8de6-47e4-bfe5-e4ecf0e94d46' \
--header 'Authorization: ••••••'

Response:
{
    "data": {
        "id": "58c49e27-8de6-47e4-bfe5-e4ecf0e94d46",
        "record_type": "porting_phone_number_block",
        "updated_at": "2024-06-27T20:05:18.240033Z",
        "country_code": "DE",
        "porting_order_id": "{{porting_order_id}}",
        "phone_number_type": "local",
        "created_at": "2024-06-27T20:05:18.240033Z",
        "phone_number_range": {
            "start_at": "+4926782349900",
            "end_at": "+4926782349999"
        },
        "activation_ranges": [
            {
                "start_at": "+4920123456000",
                "end_at": "+4920123456099"
            }
        ]
    }
}

All phone numbers in the deleted block will remain present on the order. The phone numbers themselves will not be deleted.

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