Pre-configuring Bundles with Porting Orders

You can now pre-configure Bundles with phone numbers on porting orders!

Couple of things to note:

• This is only available currently via API.
• As long as the order isn’t in a “ported” or “cancelled” status, bundles can be pre-configured on the porting order at any time.
• The term “pre-configure” is used throughout this guide instead of the term “associate” or “apply”. The reasoning is that bundles are not actually applied to the porting phone numbers until AFTER the phone numbers port in and are active at Telnyx. Therefore, when a bundle is pre-configured with a porting order, please ensure that you do not use that same bundle with any other port or number orders. If the same bundle is used elsewhere prior to the order porting, the pre-configured bundle will fail to be assigned to the porting phone number.

First, please ensure that you have enough available bundles to use with your porting order. Additionally, each bundle has its own criteria regarding which phone numbers are eligible to be associated with it. Please ensure that the available bundles on your account are valid for your porting order.

To view a list of all bundles associated with your account, you can visit the Bundles page in the portal. Or you can make the following API call to list your active bundles:

Note

Don't forget to update YOUR_API_KEY here.

Request:

curl --location --request GET 'https://api.telnyx.com/v2/bundle-pricing/user_bundles' \
--header 'Authorization: Bearer YOUR_API_KEY'

Response:

{
    "data": [
        {
            "id": "{{bundle_id}}",
            "active": true,
            "user_id": "{{user_id}}",
            "created_at": "2023-10-06",
            "updated_at": null,
            "billing_bundle": {
                "id": "{{billing_bundle_id}}",
                "name": "Standard",
                "slug": "standard",
                "cost_code": "BUNDLE-PRICING-STANDARD-MRC",
                "is_public": true,
                "created_at": "2023-04-03",
                "mrc_price": 5,
                "currency": "USD",
                "specs": null
            },
            "resources": [
                {
                    "id": "{{resources_id}}",
                    "resource": "{{e.164_phone_number}}",
                    "resource_type": "number",
                    "created_at": "2023-11-03",
                    "updated_at": "2023-11-03"
                }
            ]
        },
        {
            "id": "{{bundle_id}}",
            "active": true,
            "user_id": "{{user_id}}",
            "created_at": "2023-10-06",
            "updated_at": null,
            "billing_bundle": {
                "id": "{{billing_bundle_id}}",
                "name": "Standard",
                "slug": "standard",
                "cost_code": "BUNDLE-PRICING-STANDARD-MRC",
                "is_public": true,
                "created_at": "2023-04-03",
                "mrc_price": 5,
                "currency": "USD",
                "specs": null
            },
            "resources": []
        }
    ]
}

The 2 key components of that API response are:

1. id: Each bundle has its own unique bundle_id. This id will be used when pre-configuring the port order. There are 2 id attributes in the API response for each bundle. Do not use the id nested within the “billing_bundle” object. That id can be ignored.
2. resources: If the resources array is empty (i.e. "resources": []), the bundle has not been assigned to any phone number yet and the bundle can be used with the port order. If the resources array is not empty, then the phone number has been associated with a phone number already and the bundle cannot be used with the port order.

If you need to purchase additional bundles, please visit the Bundle Orders page in the portal. Additionally, please ensure that you purchase bundles that are eligible to be used with the phone numbers on your porting order.

First, you need to know the porting phone number ID for each phone number on the order. Use the following API command to list the phone numbers and their associated porting phone number ID’s (idin the API response):

Request:

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

Response:

{
    "data": [
        {
            "id": "{{porting_phone_number_id}}",
            "record_type": "porting_phone_number",
            "phone_number": "{{e.164_phone_number}}",
            "porting_order_id": "{{porting_order_id}}",
            "portability_status": "confirmed",
            "phone_number_type": "local",
            "messaging_port_status": null,
            "activation_status": null,
            "support_key": null,
            "requirements_status": "requirement-info-pending",
            "porting_order_status": "draft"
        }
    ],
    "meta": {
        "page_number": 1,
        "page_size": 25,
        "total_pages": 1,
        "total_results": 1
    }
}

To pre-configure a bundle with a phone number on your porting order, please use the following API request, where:

• porting_phone_number_id = the porting phone number ID for a phone number on your porting order.
• user_bundle_id = the bundle_id that you are planning to pre-configure the porting phone number with.

Request:

curl --location --request POST 'https://api.telnyx.com/v2/porting_orders/phone_number_configurations' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer [redacted]' \
--data '{
  "phone_number_configurations": [
    {
      "porting_phone_number_id": "{{porting_phone_number_id}}",
      "user_bundle_id": "{{bundle_id}}"
    }
  ]
}'

Response:

{
    "data": [
        {
            "id": "3b3cebbd-b937-4549-9789-2e2d24f514a7",
            "record_type": "porting_phone_number_configuration",
            "updated_at": "2023-11-13T20:56:05.177759Z",
            "user_bundle_id": "{{bundle_id}}",
            "created_at": "2023-11-13T20:56:05.177752Z",
            "porting_phone_number_id": "{{porting_phone_number_id}}"
        }
    ]
}

A couple of things to note about pre-configuring a bundle with a porting phone number:

• Please ensure that the bundle you are using is valid for the porting phone number. Otherwise, you will receive an error with your API request.
• You can use that API request to pre-configure a bundle with a porting phone number. And you can use the same request to update which bundle is pre-configured with a phone number (i.e. if you needed to change the bundle_id for whatever reason).
• You can only update up to 20 numbers per API request. If you have more than 20 numbers on your porting order, you will need to make multiple requests to pre-configure bundles with all of them
• You are not required to pre-configure a bundle with every phone number on the porting order. Pre-configure with as many (or as few) numbers as you wish
• You can perform this API request at nearly every stage of the port order and at nearly any time. For example, you can pre-configure bundles while your order is in a draft status, or even 15 minutes prior to the FOC date/time. The only caveat is that you cannot configure bundles on already ported phone numbers or on cancelled port orders
• The bundle is not actually associated with the phone number until the phone number ports and is active within Telnyx. Therefore, once a bundle is pre-configured with a porting phone number, do not use it elsewhere. If prior to the port completing the bundle is used elsewhere (i.e. on a number order), then the bundle will fail to be applied to the porting phone number.

To view which bundles are pre-configured with phone numbers on your porting order, you can use the following API request:

Request:

curl --location --globoff --request GET 'https://api.telnyx.com/v2/porting_orders/phone_number_configurations?page[number]=1&page[size]=25&filter[porting_order_id]={{porting_order_id}}' \
--header 'Authorization: Bearer [redacted]'

Response:

{
    "data": [
        {
            "id": "3b3cebbd-b937-4549-9789-2e2d24f514a7",
            "record_type": "porting_phone_number_configuration",
            "updated_at": "2023-11-13T20:56:05.177759Z",
            "user_bundle_id": "{{bundle_id}}",
            "porting_phone_number_id": "{{porting_phone_number_id}}",
            "created_at": "2023-11-13T20:56:05.177752Z"
        }
    ],
    "meta": {
        "page_number": 1,
        "page_size": 25,
        "total_pages": 1,
        "total_results": 1
    }
}