Skip to main content

Advanced Orders

What is this API? ​

This API enables you to submit and track Advanced Order requests when your phone number search returns zero results. If Telnyx has no inventory available for your search criteria, you can submit an Advanced Order asking Telnyx to acquire the requested numbers on your behalf.

When would this API be used? ​

When you search for numbers, four outcomes are possible:

  1. The search returns available phone numbers that you can purchase.
  2. The search targets a region where Telnyx has no coverage, resulting in a 4xx response.
  3. The request errors out due to a server issue (5xx) or a timeout.
  4. Telnyx has coverage but no available numbers matching the given search criteria. This is when the Advanced Order Request API is useful.

In case (4), you can submit an Advanced Order request to attempt to acquire phone numbers that are currently unavailable. Telnyx's Number Operations team will receive the Advanced Order and attempt to acquire the phone numbers you are requesting.

Note

  • Advanced Orders are best-effort. Telnyx may not be able to fulfill all Advanced Order requests.
  • If successful, Telnyx will order and activate the numbers for you. The orders attribute in the API response will list the order IDs of the orders that Number Ops placed to fulfill the request.
  • If unsuccessful, the request will transition to a failed status.
  • Advanced Orders are only possible when there are no available phone numbers in Telnyx's inventory that match your request criteria.

How it works ​

1. Search for phone numbers to purchase ​

First, search for your phone numbers using the GET v2/available_phone_numbers endpoint (API reference here).

You can follow this developer guide to see what filtering options are available for finding the right phone numbers for your use case.

If no results are returned, you can try to adjust your search filters to find similar phone numbers that are immediately available.

2. If no results are returned, create an Advanced Order ​

If no results are returned for your search (even after attempting to find alternatives), create an Advanced Order using the POST /v2/advanced_orders endpoint (API reference here). In the body of the request, include the same values that you were using as search parameters previously.

Example request:

Request:
curl --location --request POST 'https://api.telnyx.com/v2/advanced_orders' \
--header 'telnyx-auth-rev2;' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: ••••••' \
--data '{
  "country_code": "NL",
  "comments": "Order for business expansion",
  "quantity": 10,
  "area_code": "122",
  "nxx": "",
  "phone_number_type": "local",
  "features": ["voice"],
  "customer_reference": "",
  "requirement_group_id": null
}'

Response:
{
    "data": {
        "country_code": "NL",
        "comments": "Order for business expansion",
        "quantity": 10,
        "area_code": "122",
        "city": "",
        "nxx": "",
        "phone_number_type": "local",
        "features": [
            "voice"
        ],
        "customer_reference": "",
        "id": "a6d6633e-824b-4042-a2b7-5ac0cccd799b",
        "status": "pending",
        "orders": [],
        "created_at": "2025-09-23T20:18:04.338260",
        "updated_at": "2025-09-23T20:18:04.351892",
        "advanced_order_requirements": []
    }
}

3. View the Advanced Orders ​

When you create an Advanced Order, Telnyx adds it to the Number Operations queue for processing. The Number Operations team will attempt to acquire the requested phone numbers on your behalf. If successful, the team will order and activate the numbers for you. The orders attribute in the API response will contain the IDs of the orders placed to complete the request. This process is asynchronous.

You can query your Advanced Orders to check their status in two ways. First, you can list all of your Advanced Orders by performing a GET v2/advanced_orders request (API reference here). This endpoint has filters to narrow your search.

Example request:

Request:
curl --location --globoff --request GET 'https://api.telnyx.com/v2/advanced_orders?filter[country_code]=NL&filter[status]=pending' \
--header 'telnyx-auth-rev2;' \
--header 'Accept: application/json' \
--header 'Authorization: ••••••'

Response:
{
    "data": [
        {
            "country_code": "NL",
            "comments": "Order for business expansion",
            "quantity": 10,
            "area_code": "122",
            "city": "",
            "nxx": "",
            "phone_number_type": "local",
            "features": [
                "voice"
            ],
            "customer_reference": "",
            "id": "a6d6633e-824b-4042-a2b7-5ac0cccd799b",
            "status": "pending",
            "orders": [],
            "created_at": "2025-09-23T20:18:04.338260",
            "updated_at": "2025-09-23T20:18:04.351892",
            "advanced_order_requirements": []
        }
    ],
    "meta": {
        "page_number": 1,
        "page_size": 25,
        "total_results": 1,
        "total_pages": 1
    }
}

Second, to query a specific Advanced Order by ID, you can issue a GET v2/advanced_orders/{id} request instead (API reference here).

Example request:

Request:
curl --location --request GET 'https://api.telnyx.com/v2/advanced_orders/a6d6633e-824b-4042-a2b7-5ac0cccd799b' \
--header 'telnyx-auth-rev2;' \
--header 'Accept: application/json' \
--header 'Authorization: ••••••'

Response:
{
    "data": {
        "country_code": "NL",
        "comments": "Order for business expansion",
        "quantity": 10,
        "area_code": "122",
        "city": "",
        "nxx": "",
        "phone_number_type": "local",
        "features": [
            "voice"
        ],
        "customer_reference": "",
        "id": "a6d6633e-824b-4042-a2b7-5ac0cccd799b",
        "status": "pending",
        "orders": [],
        "created_at": "2025-09-23T20:18:04.338260",
        "updated_at": "2025-09-23T20:18:04.351892",
        "advanced_order_requirements": []
    }
}

Advanced Order statuses ​

Advanced Orders can have one of the following statuses:

  • pending: The Advanced Order has been created but is not yet being processed by Telnyx.
  • processing: The Advanced Order is currently being processed by Telnyx.
  • ordered: The Advanced Order has been successfully placed and fulfilled.
  • failed: The Advanced Order could not be completed.

4. Add regulatory requirements to an Advanced Order ​

In certain countries, our Number Ops team can only procure phone numbers if you provide the necessary regulatory requirements. In these cases, Number Ops will reach out and ask you to provide the applicable regulatory requirements.

  1. Create a requirement group that matches the "country" and "phone number type" of your Advanced Order.
  2. Make a PATCH https://api.telnyx.com/v2/advanced_orders/:order_id/requirement_group request. Use the requirement group id as the "requirement_group_id" value in the request body. This associates the requirements from your requirement group with the Advanced Order.
  3. If you need to edit the requirements associated with the Advanced Order, edit them on the requirement group first. Then PATCH v2/advanced_orders/:order_id/requirement_group the Advanced Order again. The updated requirements will override the original ones you submitted.

After you PATCH the order with a fulfilled requirement group, the advanced_order_requirements array will contain the values from your requirement group.

Example request:

Request:
curl --location --request PATCH 'https://api.telnyx.com/v2/advanced_orders/a6d6633e-824b-4042-a2b7-5ac0cccd799b/requirement_group' \
--header 'Content-Type: application/json' \
--header 'Authorization: ••••••' \
--data '{
  "requirement_group_id": "9af1bd37-e38e-435d-8d75-1575a0eaead8"
}'

Response:
{
    "data": {
        "country_code": "NL",
        "comments": "Order for business expansion",
        "quantity": 10,
        "area_code": "122",
        "city": "",
        "nxx": "",
        "phone_number_type": "local",
        "features": [
            "voice"
        ],
        "customer_reference": "",
        "id": "a6d6633e-824b-4042-a2b7-5ac0cccd799b",
        "status": "pending",
        "orders": [],
        "created_at": "2025-09-23T20:18:04.338260",
        "updated_at": "2025-09-23T20:18:04.351892",
        "advanced_order_requirements": [
            {
                "field_type": "textual",
                "requirement_id": "2708e569-696a-4fc7-9305-5fdb3eb9c7dd",
                "field_value": "test"
            },
            {
                "field_type": "address",
                "requirement_id": "a7d9a3a3-70ed-4cb4-821b-b94e8ea6dc9b",
                "field_value": "2583037091860448979"
            },
            {
                "field_type": "document",
                "requirement_id": "b0197fa1-c2fd-4500-9875-2c658b2396eb",
                "field_value": "dd5b3032-ca5f-41b9-beff-d5570f611c45"
            },
            {
                "field_type": "document",
                "requirement_id": "ec029bc6-357f-404d-bdfd-f61d4e578896",
                "field_value": "dd5b3032-ca5f-41b9-beff-d5570f611c45"
            },
            {
                "field_type": "document",
                "requirement_id": "f39fbfaa-336d-40d9-bbc4-21082446ed07",
                "field_value": "dd5b3032-ca5f-41b9-beff-d5570f611c45"
            }
        ]
    }
}

5. Finish the number ordering process ​

When an Advanced Order transitions to ordered status, Number Ops has placed a number order on your account for the requested phone numbers.

Check the orders array in the Advanced Order API response to see which number orders were placed. The orders array lists the Number Order IDs for the orders that were placed.

Example:

Request:
curl --location --globoff --request GET 'https://api.telnyx.com/v2/advanced_orders?filter[country_code]=NL&filter[status]=ordered' \
--header 'telnyx-auth-rev2;' \
--header 'Accept: application/json' \
--header 'Authorization: ••••••'

Response:
{
    "data": [
        {
            "country_code": "NL",
            "comments": "Order for business expansion",
            "quantity": 10,
            "area_code": "122",
            "city": "",
            "nxx": "",
            "phone_number_type": "local",
            "features": [
                "voice"
            ],
            "customer_reference": "",
            "id": "a6d6633e-824b-4042-a2b7-5ac0cccd799b",
            "status": "ordered",
            "orders": [
                "4d1e42dd-0f84-4869-b0d3-e0b1e961413a",
                "82ca2465-bdb0-4ef4-aab6-d24248986226",
                "af829c8f-1429-41d4-9e10-d353fdfb8717"
            ],
            "created_at": "2025-09-23T20:18:04.338260",
            "updated_at": "2025-09-23T20:38:19.509699",
            "advanced_order_requirements": [
                {
                    "field_type": "textual",
                    "requirement_id": "2708e569-696a-4fc7-9305-5fdb3eb9c7dd",
                    "field_value": "test"
                },
                {
                    "field_type": "address",
                    "requirement_id": "a7d9a3a3-70ed-4cb4-821b-b94e8ea6dc9b",
                    "field_value": "2583037091860448979"
                },
                {
                    "field_type": "document",
                    "requirement_id": "b0197fa1-c2fd-4500-9875-2c658b2396eb",
                    "field_value": "dd5b3032-ca5f-41b9-beff-d5570f611c45"
                },
                {
                    "field_type": "document",
                    "requirement_id": "ec029bc6-357f-404d-bdfd-f61d4e578896",
                    "field_value": "dd5b3032-ca5f-41b9-beff-d5570f611c45"
                },
                {
                    "field_type": "document",
                    "requirement_id": "f39fbfaa-336d-40d9-bbc4-21082446ed07",
                    "field_value": "dd5b3032-ca5f-41b9-beff-d5570f611c45"
                }
            ]
        }
    ],
    "meta": {
        "page_number": 1,
        "page_size": 25,
        "total_results": 1,
        "total_pages": 1
    }
}

You can then use the GET v2/number_orders/:number_order_id request (API reference here) to:

  • View details about the actual number order that was placed.
  • View which phone numbers were ordered.
  • View the status of the order.
  • View if there are any regulatory requirements to be fulfilled.

At this point, treat these new number orders like any other number order. If the Advanced Order was for a phone number with regulatory requirements, you must fulfill these and await approval before the phone number is active.

Comments ​

You can communicate with the Number Operations team about your request through comments. Use the Comments API to retrieve and create comments associated with an Advanced Order request.

Retrieving comments ​

To retrieve comments related to an Advanced Order request, make a GET request to the /comments endpoint (API reference here). To filter comments for a specific order, specify advanced_number_order in filter[comment_record_type] and provide the order ID in filter[comment_record_id].

Example API request:

curl --location --globoff --request GET 'https://api.telnyx.com/v2/comments?filter[comment_record_type]=advanced_number_order&filter[comment_record_id]=a6d6633e-824b-4042-a2b7-5ac0cccd799b' \
--header 'Authorization: ••••••'

Response:

{
    "data": [
        {
            "comment_record_type": "advanced_number_order",
            "id": "79e8ef88-a79b-4a4c-8dcf-f777a023eb57",
            "read_at": null,
            "commenter_type": "admin",
            "updated_at": "2025-09-23T20:38:07.739268+00:00",
            "created_at": "2025-09-23T20:38:07.739266+00:00",
            "body": "This is an admin comment",
            "comment_record_id": "a6d6633e-824b-4042-a2b7-5ac0cccd799b",
            "commenter": "brandon@telnyx.com",
            "record_type": "comment"
        },
        {
            "comment_record_type": "advanced_number_order",
            "id": "4465f92d-f8e3-4c69-9c8c-063f7fc95e37",
            "read_at": null,
            "commenter_type": "user",
            "updated_at": "2025-09-23T20:42:17.881512+00:00",
            "created_at": "2025-09-23T20:42:17.881512+00:00",
            "body": "test comment from user",
            "comment_record_id": "a6d6633e-824b-4042-a2b7-5ac0cccd799b",
            "commenter": "brandon@telnyx.com",
            "record_type": "comment"
        }
    ],
    "meta": {
        "total_pages": 1,
        "total_results": 2,
        "page_number": 1,
        "page_size": 25
    }
}

Creating a comment ​

To add a comment to an Advanced Order request, make a POST request to the /comments endpoint (API reference here). The request body must include the comment text (body), the record type (comment_record_type), and the order ID (comment_record_id).

Example API request:

curl --location --request POST 'https://api.telnyx.com/v2/comments' \
--header 'Content-Type: application/json' \
--header 'Authorization: ••••••' \
--data '{
  "body": "test comment from user",
  "comment_record_type": "advanced_number_order",
  "comment_record_id": "a6d6633e-824b-4042-a2b7-5ac0cccd799b"
}'

Response:

{
    "data": {
        "body": "test comment from user",
        "commenter_type": "user",
        "read_at": null,
        "comment_record_type": "advanced_number_order",
        "updated_at": "2025-09-23T20:42:17.881512+00:00",
        "comment_record_id": "a6d6633e-824b-4042-a2b7-5ac0cccd799b",
        "commenter": "brandon@telnyx.com",
        "id": "4465f92d-f8e3-4c69-9c8c-063f7fc95e37",
        "created_at": "2025-09-23T20:42:17.881512+00:00",
        "record_type": "comment"
    }
}

Notifications ​

You can set up email and/or webhook notifications for your Advanced Orders. These notifications provide status updates on your requests. Follow this guide to learn more about configuring notifications.

Webhook events ​

Advanced Order is created: ​

{
  "data": {
    "event_type": "advanced_order.status_update",
    "id": "83996511-474b-4cbe-afc3-14c9c0144404",
    "occurred_at": "2025-09-23T20:18:04.789361Z",
    "payload": {
      "new_status": "pending",
      "old_status": "created",
      "order_id": "a6d6633e-824b-4042-a2b7-5ac0cccd799b"
    },
    "record_type": "event"
  },
  "meta": {
    "attempt": 1,
    "delivered_to": "https://webhook.site/a61372df-394b-4c61-a601-79b35421824a"
  }
}

Transition from pending to processing: ​

{
  "data": {
    "event_type": "advanced_order.status_update",
    "id": "e5704883-c9d5-40f4-b089-d48495b1e14e",
    "occurred_at": "2025-09-23T20:36:40.616041Z",
    "payload": {
      "new_status": "processing",
      "old_status": "pending",
      "order_id": "a6d6633e-824b-4042-a2b7-5ac0cccd799b"
    },
    "record_type": "event"
  },
  "meta": {
    "attempt": 1,
    "delivered_to": "https://webhook.site/a61372df-394b-4c61-a601-79b35421824a"
  }
}

Transition from processing to ordered: ​

{
  "data": {
    "event_type": "advanced_order.status_update",
    "id": "b2f454f0-99b8-45df-81e6-1384f4233549",
    "occurred_at": "2025-09-23T20:38:19.742838Z",
    "payload": {
      "new_status": "ordered",
      "old_status": "processing",
      "order_id": "a6d6633e-824b-4042-a2b7-5ac0cccd799b"
    },
    "record_type": "event"
  },
  "meta": {
    "attempt": 1,
    "delivered_to": "https://webhook.site/a61372df-394b-4c61-a601-79b35421824a"
  }
}

Transition from processing to failed: ​

{
  "data": {
    "event_type": "advanced_order.status_update",
    "id": "607d5f1b-2763-4dd1-8ced-ebf786f70996",
    "occurred_at": "2025-09-23T20:39:10.729398Z",
    "payload": {
      "new_status": "failed",
      "old_status": "processing",
      "order_id": "7c179258-e676-4844-81a4-a6cb626075db"
    },
    "record_type": "event"
  },
  "meta": {
    "attempt": 1,
    "delivered_to": "https://webhook.site/a61372df-394b-4c61-a601-79b35421824a"
  }
}

New Comment: ​

{
  "data": {
    "event_type": "advanced_order.new_comment",
    "id": "236a47ea-ac71-4df0-aa3e-55f249c72818",
    "occurred_at": "2025-09-23T20:38:07.990291Z",
    "payload": {
      "advanced_order_id": "a6d6633e-824b-4042-a2b7-5ac0cccd799b",
      "comment": "This is an admin comment"
    },
    "record_type": "event"
  },
  "meta": {
    "attempt": 1,
    "delivered_to": "https://webhook.site/a61372df-394b-4c61-a601-79b35421824a"
  }
}