# Telnyx Numbers: Global Phone Numbers — Full Documentation > Complete page content for Global Phone Numbers (Numbers section) of the Telnyx developer docs (https://developers.telnyx.com). > Root index: https://developers.telnyx.com/llms.txt · Lightweight index for this subsection: https://telnyx-openapi-ng.s3.us-east-1.amazonaws.com/llms/numbers/global-phone-numbers.txt ## Coverage ### Getting started with Telnyx phone number APIs > Source: https://developers.telnyx.com/docs/numbers/phone-numbers/getting-started.md ### Overview: The following concepts must be understood to purchase phone numbers. ### Coverage Telnyx sells phone numbers in **100+ countries** across multiple phone number types. To see a list of supported countries and number types, query the [Get Country Coverage API](https://developers.telnyx.com/api-reference/country-coverage/get-country-coverage). The response includes: - Countries - Available phone number types within each country - Applicable phone number attributes - If the inventory coverage API (inventory_coverage=true) is supported If inventory coverage is supported, use the [Inventory Coverage API](https://developers.telnyx.com/api-reference/inventory-level/create-an-inventory-coverage-request) to assess how many numbers are available based on your search criteria. ### Regulatory Requirements Prior to number activation, some phone numbers need additional information to satisfy regulatory requirements.  **Requirement Resources** | Feature | Description | | :------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------- | | [Compliance Page](https://portal.telnyx.com/#/numbers/requirements) | View regulatory requirements for all countries in the Telnyx Portal | | [Developer Guide](https://developers.telnyx.com/api-reference/requirements/list-all-requirements) | Guide discussing regulatory requirements in more detail, including relevant API requests. | | [Requirement Groups](https://developers.telnyx.com/docs/numbers/phone-numbers/requirement-groups) | Stores pre-filled regulatory information to be assigned to orders. | ### Search Search for available phone numbers using the [List Available Phone Numbers API](https://developers.telnyx.com/api-reference/phone-number-search/list-available-phone-numbers) .  For a deeper dive into search strategies, check out the [Number Search Guide](https://developers.telnyx.com/docs/numbers/phone-numbers/number-search). ### Reserve [Reserve phone numbers](https://developers.telnyx.com/docs/numbers/phone-numbers/number-reservations) to block other users from purchasing them. Reservations expire after 30 minutes. Not all phone numbers are reservable.  ### Order Purchase phone numbers using the [Create Number Order API](https://developers.telnyx.com/api-reference/phone-number-orders/create-a-number-order) . Numbers in the order must come from a prior search for the order to be accepted. ### Advanced Order Advanced Orders are a fallback mechanism for inventory not found in standard search. These requests are routed to the Number Operations team for manual sourcing and are added to the account upon acquisition. Submit an [Advanced Order](https://developers.telnyx.com/api-reference/advanced-number-orders/create-advanced-order) and our Number Operations team will attempt to acquire the numbers you need. Once sourced, they’ll be added directly to your account for activation. These requests are best effort. Telnyx cannot guarantee that every advanced order will be fulfilled. --- ## Searching ### Number search > Source: https://developers.telnyx.com/docs/numbers/phone-numbers/number-search.md Use the [GET v2/available_phone_numbers endpoint](https://developers.telnyx.com/api-reference/phone-number-search/list-available-phone-numbers) to search for phone numbers that are available to purchase. ## Constraints - To order a phone number, it must have been returned in a recent search request - Country code is always required in search requests. The rest of the fields are optional - Wildcard characters (\*, %, etc.) are not supported in any of the filters. If a wildcard character is included in a filter, the search will yield 0 results. - Depending on your [account verification level](https://developers.telnyx.com/docs/account-setup/levels-and-capabilities/index#account-levels-and-capabilities), search results may be limited. ## Best Practices - When supported, use the [inventory coverage API](https://developers.telnyx.com/api-reference/inventory-level/create-an-inventory-coverage-request#create-an-inventory-coverage-request) to list possible values for a variety of filters, including area code and city. - Use the `features` filter (filter[features]) to search for phone numbers with capabilities that satisfy your use case - If you need phone numbers that are able to place outbound calls, search for phone numbers with `emergency` as a feature - If you need phone numbers that are SMS capable, search for phone numbers with `sms` as a feature. Any phone number with `sms` as a feature should be capable and ready to immediately leverage SMS. - For US toll-free phone numbers, we recommend using the `quickship` filter (filter[quickship]=true) in your search request. In doing so, you will be purchasing a phone number that is pre-provisioned and usable immediately. If you can’t find what you are looking for, you can disable the quickship filter to expand the possible search results. Just be aware that it could take up to 2 business days for a non-quickship toll-free phone number to be fully active after purchase. - Not all phone numbers are the same price. Review the `cost_information` object  in the API response to see how much each phone number will cost before purchasing. ## Filter for specific phone numbers There are a variety of filters to narrow down your search and find your desired number. ### Required Filters - **Country Code (**`filter[country_code]`**)**: Search for phone numbers in a specific country. This filter must be included in every search. Use [ISO 3166 2 letter](https://www.iban.com/country-codes) country codes. ### Standard Filters - **Feature (**`filter[features]`**)**: Phone numbers have varying capabilities. Filter for phone numbers that have the features to satisfy your use case. I.e. “sms” will return phone numbers that support SMS, “emergency” will return phone numbers capable of placing emergency calls, etc. - **Type (**`filter[phone_number_type]`**)**: Filter for a specific type of phone number. I.e. “local” will return local/geographic phone numbers, “toll-free” will return toll-free phone numbers only, etc. - **Area Code (**`filter[national_destination_code]`**)**: Search for phone numbers in a given area code. I.e. “205” will return phone numbers with a “205” area code - **City / Region (**`filter[locality]`**)**: Search for phone numbers in a given city / region / rate center. I.e. “Boston” would return phone numbers in or near Boston, MA. - **[US/CA only] State / Province (**`filter[administrative_area]`**)**: Search for phone numbers in a given state / province. I.e. filtering for “MA” will return phone numbers in Massachusetts. ### Advanced Filters - **Starts with (**`filter[starts_with]`**)**: “56” will return numbers starting with “56”, i.e. +1-312-562-0011. Couple of things to note: - Never include the country code (i.e. “+1”) in the search filter. - If you are using the Area Code filter in conjunction with the Starts with filter, do not include the area code digits in the starts with filter. I.e. if you wanted to find +1-312-562-0011, you would use Area Code = 312 and Starts With = 562. - If you are not using the Area Code filter, include the area code digits in the starts with filter. I.e. if you wanted to find +1-312-562-0011, you would use Starts With = 312562. - **Ends with (**`filter[ends_with]`**)**: “356” will return numbers ending with “356”, i.e. +1-312-562-0356. - **Contains (**`filter[contains]`**)**: “56” will return numbers matching “5” and ”6” anywhere, i.e. +1-312-622-0533. - **Consecutive Numbers (**`filter[consecutive]`**)**: Range of successive phone numbers. I.e. entering “3” will return +1-312-562-0011, +1-312-562-0012, and +1-312-562-0013 in the search results - **Results Limit (**`filter[limit]`**)**: Define the maximum quantity of phone numbers in the search results. I.e. “2” will return a maximum of 2 phone numbers in your search results - **[US / CA only] Best Effort (**`filter[best_effort]`**)**: Telnyx may not have phone numbers that meet your exact search criteria. If that’s the case and “Best Effort” is toggled on, Telnyx will return similar results that meet some of your criteria. - **[US toll-free only] Quickship (**`filter[quickship]`**)**: When “Quickship” is toggled on, the toll-free phone numbers returned in search are pre-provisioned and ready for immediate activation. When “Quickship” is toggled off, a phone number may be returned that is not pre-provisioned. If that phone number is purchased, it can take up to 2 business days for provisioning to complete and the phone number to be usable. If the filter is toggled on and you are searching for something that isn’t a US toll-free phone number, then the filter will be ignored. - **Reservable Numbers (**`filter[reservable]`**)**: Returns phone numbers that are eligible to be reserved. When a phone number is reserved, you will have exclusive rights to search and order the phone number for a period of 30 minutes. More details [here](https://developers.telnyx.com/docs/numbers/phone-numbers/number-reservations). - **Exclude Held Numbers (**`filter[exclude_held_numbers]`**)**: A phone number can be on "hold" in two instances. Either the phone number was recently deleted and is in the process of being recycled. Or the phone number was placed on hold by Telnyx's Number Ops team for you to search and purchase. Enabling this filter will exclude any phone numbers in a "hold" status from the search results. - **Held / Reserved (**`filter[only_reserved_numbers]`**)**: Returns phone numbers that are already set aside for the requesting customer, meaning numbers currently in either hold status (e.g., recently deleted numbers still in the recovery/grace period, or numbers placed on hold by Number Ops) or reserved status. Use this filter to surface numbers you can reclaim or repurchase before they return to general availability. --- ## Ordering ### Number reservations > Source: https://developers.telnyx.com/docs/numbers/phone-numbers/number-reservations.md ## Overview The Phone Number Reservations API lets you **reserve** phone numbers for 30 minutes. During this period, you have exclusive rights to search for and order the reserved phone number. After 30 minutes, the number is returned to the `available` pool, making it accessible for other users to search for and order. ## Constraints: - Not all phone numbers are reservable. - Reservations expire after 30 minutes ## Reservation Flow ### Step 1: Search for reservable phone numbers To ensure only reservable phone numbers are included in [your search results](https://developers.telnyx.com/api-reference/phone-number-search/list-available-phone-numbers), add the filters `filter[reservable]=true` and `filter[exclude_held_numbers]=true` to your search request. ### Step 2: Create a reservation To reserve one or more phone numbers, send a `POST https://api.telnyx.com/v2/number_reservations` request ([API reference here](https://developers.telnyx.com/api-reference/phone-number-reservations/create-a-number-reservation)). A couple of important attributes in the API response to consider: - `id`: Unique ID associated with the overall number reservation request. - `status`: Status of the overall reservation request. - `phone_numbers[].status`: status of the individual phone number reservation. - `phone_numbers[].expired_at`: Expiration timestamp for the individual phone number reservation. Once this timestamp is exceeded, the phone number will be returned to the `available` pool for other users to search and order. When the request is submitted, each phone number will be individually attempted for reservation. Some phone numbers may fail to be reserved (i.e., already purchased or reserved). In such cases, the `phone_numbers[].status` will be `failed`, and the overall request `status` will be `partial_success`. ### List all reservations To view a list of all your number reservations, send a `GET https://api.telnyx.com/v2/number_reservations` request ([API reference here](https://developers.telnyx.com/api-reference/phone-number-reservations/list-number-reservations)). ### Extend a reservation To extend your reservation by another 30 minutes, send a `POST https://api.telnyx.com/v2/number_reservations/{{id}}/actions/extend` request ([API reference here](https://developers.telnyx.com/api-reference/phone-number-reservations/extend-a-number-reservation)). This request will update the `phone_numbers[].expired_at` timestamp to reflect the additional 30 minutes. --- ### Number orders > Source: https://developers.telnyx.com/docs/numbers/phone-numbers/number-orders.md This guide will walk you through how to order phone numbers. ## Ordering Flow ### Step 1: Search for phone numbers. Use the [GET /available_phone_numbers](https://developers.telnyx.com/api-reference/phone-number-search/list-available-phone-numbers) endpoint to search for phone numbers to purchase. [See this guide](https://developers.telnyx.com/docs/numbers/phone-numbers/number-search) for more details. Only phone numbers that were previously returned in a search request can be ordered. ### Step 2: Create an order Use the [POST /number_orders endpoint](https://developers.telnyx.com/api-reference/phone-number-orders/create-a-number-order) to create an order.  Note: in some countries, a "requirement group" needs to be included in the payload for the `POST /number_orders` API request. For more details, [check out this guide](https://developers.telnyx.com/docs/numbers/phone-numbers/requirement-groups). ### Step 3: Regulatory Requirements If the order does not have regulatory requirements, then it should activate momentarily with no further user action. The rest of the flow outlined (Step 3 and Step 4) is irrelevant in this case. However, phone numbers in most countries have regulatory requirements.  Perform a [GET sub_number_orders/{sub_number_order_id} request](https://developers.telnyx.com/api-reference/phone-number-orders/retrieve-a-sub-number-order) to see the regulatory requirements for that order (in the `regulatory_requirements` array). Once you have collected the necessary information, perform a [PATCH /sub_number_orders/{sub_number_order_id} request](https://developers.telnyx.com/api-reference/phone-number-orders/update-a-sub-number-orders-requirements) to associate that information to the number order. For more information on regulatory requirements, check out this guide. ### Step 4: Handling Regulatory Requirement Rejections All regulatory requirements on an order are vetted individually. Once all regulatory requirements are vetted and approved, the order will complete. To check on the regulatory requirement vetting status, perform a [GET /number_order_phone_numbers request](https://developers.telnyx.com/api-reference/phone-number-orders/retrieve-a-list-of-phone-numbers-associated-to-orders). It is possible that some (or all) of the information provided is rejected. If a rejection occurs: - Determine which regulatory requirement(s) was rejected - [Review the comments](https://developers.telnyx.com/api-reference/phone-number-orders/retrieve-all-comments) on the order to see a more detailed explanation why the regulatory requirement(s) was rejected - Update the order with any corrections, and resubmit for approval ## “Number Order” vs “Sub Number Order” “Number Orders” and “Sub Number Orders” share a parent - child relationship: - “Number Order” = “parent”. Overarching order entity.  - “Sub Number Order” = “child”. Nested within the “number order”. The `POST /number_orders` request will always create one (1) “number order”. However, it could be split into multiple “sub number orders” depending on the phone numbers you are purchasing. For example, if you created a number order that included the following: - 5 `local` phone numbers in Country A - 5 `toll_free` phone numbers in Country A - 5 `local` phone numbers in Country B Then the request would be 1 number order with 3 nested sub number orders. Sub number orders are processed independently, even if they are a part of the same number order. ## Order Statuses Number orders / sub number orders have a few possible statuses: | Status | Description | | :-------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | pending | Order was created and is being processed. Phone numbers are not yet active. | | success | Order completed successfully. Phone numbers were activated. | | failure | There was an issue with the order. | | cancelled | The order was cancelled. [Either by the user](https://developers.telnyx.com/api-reference/phone-number-orders/cancel-a-sub-number-order), or by the Telnyx team. | | deleted | All phone numbers on the order have been deleted from the user account. | When a number order / sub number order is in a `pending` status, [the phone number status](https://developers.telnyx.com/api-reference/phone-number-orders/retrieve-a-list-of-phone-numbers-associated-to-orders) will give insight into the vetting process. Phone numbers can have the following statuses while an order is `pending`: | Status | Description | | :---------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | requirement-info-pending | Order is missing values for one or more regulatory requirements. Customer needs to provide additional information to fulfill all requirements before vetting can proceed. | | requirement-info-under-review | Customer has provided values for all regulatory requirements. Order is awaiting vetting by Number Ops | | requirement-info-exception | One or more of the regulatory requirements have been rejected by Number Ops. Customer needs to review the rejections, make corrections, and resubmit | | approved | All requirements are approved. | | deleted | All phone numbers on the order have been deleted from the user account. | ## Deadline + Auto Cancellation Each order has a `deadline` attribute. Users are expected to have all regulatory requirements uploaded by the deadline, at which point the `deadline` is erased. Failure to provide all regulatory requirements by the deadline will result in auto-cancellation of the order. If one or more regulatory requirements are rejected, a new deadline will be set. The user will have until the new deadline to make corrections to avoid auto-cancellation. Deadlines can be extended upon request via comment on the order. ## Webhook notifications [Follow this support article](https://support.telnyx.com/en/articles/4277896-notification-settings) to set up webhook notifications for order events.  Select the Notification Setting “Number Order Notifications: for all number order notifications”. --- ### Advanced Orders > Source: https://developers.telnyx.com/docs/numbers/phone-numbers/advanced-orders.md ## **Overview** 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. Telnyx's Number Operations team will attempt to acquire the phone numbers that are currently unavailable. If successful, the team will order and activate the numbers on your account. This process is asynchronous. ## Constraints - Not eligible for US or CA toll free phone numbers. The search API reflects all possible inventory. - Not eligible for unique phone numbers (i.e. I request phone number 123-456-7890, I request a phone number that ends in 0000, etc.). - Advanced orders are best effort. Telnyx cannot guarantee that we will be able to procure the phone numbers you request. ## Advanced Order 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. - **exception**: There is an issue with the advanced order. Please review it and take the appropriate actions to resolve the issue. - **hold**: Telnyx needs to replenish our inventory to fulfill your request. This process can take some time. No further action is needed on your end, the order will remain in this status until Telnyx is able to replenish those phone numbers. - **ordered**: The Advanced Order has been successfully placed and fulfilled. - **failed**: The Advanced Order could not be completed. ## **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](/api-reference/phone-number-search/list-available-phone-numbers), [developer guide here](https://developers.telnyx.com/docs/numbers/phone-numbers/number-search)). 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](/api-reference/advanced-number-orders/create-advanced-order)). In the body of the request, include the same values that you were using as search parameters previously. ### **3. Add regulatory requirements to an Advanced Order** In most 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](https://developers.telnyx.com/docs/numbers/phone-numbers/requirement-groups) 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 ([API reference here](https://developers.telnyx.com/api-reference/advanced-number-orders/update-advanced-order)). Use the requirement group `id` as the "requirement_group_id" value in the request body. 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. ### **4. Finish the number ordering process** When an Advanced Order transitions to `ordered` status, Number Ops has placed number order(s) 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. You can then use the `GET v2/number_orders/:number_order_id` request ([API reference here](/api-reference/phone-number-orders/retrieve-a-number-order)) 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. It may require further actions by you to complete the order. ## **Comments** You can communicate with the Number Operations team about your request through the Comments API. Use `filter[comment_record_type]=advanced_number_order` and specify the advanced order ID as the `comment_record_id` in the API requests. - [View comments](https://developers.telnyx.com/api-reference/phone-number-orders/retrieve-all-comments) - [Create a comment](https://developers.telnyx.com/api-reference/phone-number-orders/create-a-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](https://support.telnyx.com/en/articles/4277896-notification-settings) 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 one status (in this example, processing) into hold:** ``` { "data": { "event_type": "advanced_order.status_update", "id": "ac65655a-897d-439e-8fe7-32a5c3fc5f13", "occurred_at": "2025-11-26T18:42:40.436059Z", "payload": { "new_status": "hold", "old_status": "processing", "order_id": "44b6f0f6-6a0c-412b-b015-55e3c2df47c6" }, "record_type": "event" }, "meta": { "attempt": 3, "delivered_to": "https://webhook.site/c9b32d02-db83-4af1-ab86-b8acdd8daabf" } } ``` **Transition from one status (in this example, hold) into exception:** ``` { "data": { "event_type": "advanced_order.status_update", "id": "f4252145-9f49-4c4a-bb1f-028a387dfc50", "occurred_at": "2025-11-26T18:42:46.867446Z", "payload": { "new_status": "exception", "old_status": "hold", "order_id": "44b6f0f6-6a0c-412b-b015-55e3c2df47c6" }, "record_type": "event" }, "meta": { "attempt": 3, "delivered_to": "https://webhook.site/c9b32d02-db83-4af1-ab86-b8acdd8daabf" } } ``` **Transition from one status (in this example, processing) into 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 one status (in this example, processing) into 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" } } ``` --- ### Bulk orders > Source: https://developers.telnyx.com/docs/numbers/phone-numbers/bulk-ordering.md ## Overview Bulk number orders (inexplicit orders) allow you to purchase phone numbers by specifying search criteria and quantity, without needing to identify and select specific phone numbers beforehand. The API automatically searches for available numbers matching your criteria, reserves them, and creates number orders on your account. This differs from the standard ordering workflow where you first [search for available numbers](https://developers.telnyx.com/docs/numbers/phone-numbers/number-search), review the results, and then [create orders](https://developers.telnyx.com/docs/numbers/phone-numbers/number-orders) for specific phone numbers. The bulk ordering process handles the search, reservation, and ordering steps automatically in a single API request. Orders are processed asynchronously, with processing time varying based on your search criteria, quantity requested, and current inventory availability. ## Constraints - Bulk orders are only available for phone numbers in the **US and CA**. - Maximum of 10,000 phone numbers per bulk order. - The API will only order numbers that are available at the time of processing. Availability is not guaranteed and depends on current inventory levels. You can use the [inventory coverage API](https://developers.telnyx.com/docs/numbers/phone-numbers/getting-started#coverage) to check inventory levels prior to ordering. ## Ordering Groups You can include multiple ordering groups in a single bulk order request. Each ordering group is processed independently and can have different search criteria and strategies. For example, you could create one bulk order that includes: - 5 local phone numbers in California, US with voice features. - 3 toll-free phone numbers in US with SMS features. - 10 local phone numbers in area code 212, New York, US. Each ordering group tracks its own `count_requested`, `count_allocated`, and `status` fields independently. ## Order Statuses Each ordering group within a bulk order has a status that indicates its current progress: | Status | Description | | :---------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | pending | The bulk order is queued and awaiting processing. | | processing | The order is actively being processed. | | success | The order was fully processed without errors. All requested phone numbers were ordered. | | partial\_success | The order was processed, but only partially completed. Some numbers could not be purchased due to insufficient inventory or errors encountered during number ordering. | | failed | The order could not be processed successfully. | ## How It Works ### Step 1: Create a bulk order Use the [POST /v2/inexplicit_number_orders endpoint](https://developers.telnyx.com/api-reference/inexplicit-number-orders/create-an-inexplicit-number-order) to create an order. Each `ordering_group` requires `country_iso` (US or CA), `count_requested`, and `phone_number_type`. Optionally include [search filters](https://developers.telnyx.com/docs/numbers/phone-numbers/number-search) to narrow down results. You can specify a `strategy` that controls behavior when inventory is insufficient: `always` (default) orders whatever quantity is available, while `never` only places the order if the full quantity can be fulfilled. You can also configure `connection_id`, `messaging_profile_id`, `billing_group_id`, or `customer_reference` to automatically apply settings to all ordered phone numbers. ### Step 2: Monitor order status You can check the status of your bulk orders using the following endpoints: - [GET /v2/inexplicit_number_orders](https://developers.telnyx.com/api-reference/inexplicit-number-orders/list-inexplicit-number-orders): List all bulk orders with pagination support. - [GET /v2/inexplicit_number_orders/{id}](https://developers.telnyx.com/api-reference/inexplicit-number-orders/retrieve-an-inexplicit-number-order): Retrieve a specific bulk order by ID. Monitor the `status` field to track progress, and compare `count_allocated` to `count_requested` to see how many numbers were successfully ordered in each ordering group. ### Step 3: Access the created number orders When the bulk order completes processing, the `orders` array in the API response shows the number orders that were created to fulfill your request. Each entry includes: - **number_order_id**: The ID of the parent number order. - **sub_number_order_ids**: An array of sub number order IDs associated with the parent order. You can retrieve details about these orders using the standard number ordering APIs: - [GET /v2/number_orders/{number_order_id}](https://developers.telnyx.com/api-reference/phone-number-orders/retrieve-a-number-order): Retrieve the parent number order. - [GET /v2/sub_number_orders](https://developers.telnyx.com/api-reference/phone-number-orders/list-sub-number-orders): List sub number orders. From this point, follow the standard [number ordering workflow](https://developers.telnyx.com/docs/numbers/phone-numbers/number-orders) to complete any remaining steps. ## Webhook Notifications You can configure webhook notifications to receive updates about your orders. [Follow this support article](https://support.telnyx.com/en/articles/4277896-notification-settings) to set up webhook notifications. Select the "Number Order Notifications" notification setting to receive webhooks for all number order events. Note that webhook events are generated by the underlying number orders created by the bulk order, not by the bulk order itself. --- ## API Reference (Global Phone Numbers) ### Country Coverage - [Get country coverage](https://developers.telnyx.com/api-reference/country-coverage/get-country-coverage.md): Get country coverage - [Get coverage for a specific country](https://developers.telnyx.com/api-reference/country-coverage/get-coverage-for-a-specific-country.md): Get coverage for a specific country ### Inventory Level - [Create an inventory coverage request](https://developers.telnyx.com/api-reference/inventory-level/create-an-inventory-coverage-request.md): Creates an inventory coverage request. If locality, npa or national_destination_code is used in groupBy, and no region or locality filters are used, the whole… ### Phone Number Search - [List available phone number blocks](https://developers.telnyx.com/api-reference/phone-number-search/list-available-phone-number-blocks.md) - [List available phone numbers](https://developers.telnyx.com/api-reference/phone-number-search/list-available-phone-numbers.md) ### numbers features - [Retrieve the features for a list of numbers](https://developers.telnyx.com/api-reference/numbers-features/retrieve-the-features-for-a-list-of-numbers.md): Retrieve the features for a list of numbers ### Phone Number Reservations - [List number reservations](https://developers.telnyx.com/api-reference/phone-number-reservations/list-number-reservations.md): Gets a paginated list of phone number reservations. - [Create a number reservation](https://developers.telnyx.com/api-reference/phone-number-reservations/create-a-number-reservation.md): Creates a Phone Number Reservation for multiple numbers. - [Retrieve a number reservation](https://developers.telnyx.com/api-reference/phone-number-reservations/retrieve-a-number-reservation.md): Gets a single phone number reservation. - [Extend a number reservation](https://developers.telnyx.com/api-reference/phone-number-reservations/extend-a-number-reservation.md): Extends reservation expiry time on all phone numbers. ### Phone Number Orders - [List number orders](https://developers.telnyx.com/api-reference/phone-number-orders/list-number-orders.md): Get a paginated list of number orders. - [Create a number order](https://developers.telnyx.com/api-reference/phone-number-orders/create-a-number-order.md): Creates a phone number order. - [Retrieve a number order](https://developers.telnyx.com/api-reference/phone-number-orders/retrieve-a-number-order.md): Get an existing phone number order. - [Update a number order](https://developers.telnyx.com/api-reference/phone-number-orders/update-a-number-order.md): Updates a phone number order. - [Retrieve a list of phone numbers associated to orders](https://developers.telnyx.com/api-reference/phone-number-orders/retrieve-a-list-of-phone-numbers-associated-to-orders.md): Get a list of phone numbers associated to orders. - [Retrieve a single phone number within a number order.](https://developers.telnyx.com/api-reference/phone-number-orders/retrieve-a-single-phone-number-within-a-number-order.md): Get an existing phone number in number order. - [Update requirements for a single phone number within a number order.](https://developers.telnyx.com/api-reference/phone-number-orders/update-requirements-for-a-single-phone-number-within-a-number-order.md): Updates requirements for a single phone number within a number order. - [List sub number orders](https://developers.telnyx.com/api-reference/phone-number-orders/list-sub-number-orders.md): Get a paginated list of sub number orders. - [Retrieve a sub number order](https://developers.telnyx.com/api-reference/phone-number-orders/retrieve-a-sub-number-order.md): Get an existing sub number order. - [Update a sub number order's requirements](https://developers.telnyx.com/api-reference/phone-number-orders/update-a-sub-number-orders-requirements.md): Updates a sub number order. - [Cancel a sub number order](https://developers.telnyx.com/api-reference/phone-number-orders/cancel-a-sub-number-order.md): Allows you to cancel a sub number order in 'pending' status. - [Create a sub number orders report](https://developers.telnyx.com/api-reference/phone-number-orders/create-a-sub-number-orders-report.md): Create a CSV report for sub number orders. The report will be generated asynchronously and can be downloaded once complete. - [Retrieve a sub number orders report](https://developers.telnyx.com/api-reference/phone-number-orders/retrieve-a-sub-number-orders-report.md): Get the status and details of a sub number orders report. - [Download a sub number orders report](https://developers.telnyx.com/api-reference/phone-number-orders/download-a-sub-number-orders-report.md): Download the CSV file for a completed sub number orders report. The report status must be 'success' before the file can be downloaded. - [Retrieve all comments](https://developers.telnyx.com/api-reference/phone-number-orders/retrieve-all-comments.md) - [Create a comment](https://developers.telnyx.com/api-reference/phone-number-orders/create-a-comment.md) - [Retrieve a comment](https://developers.telnyx.com/api-reference/phone-number-orders/retrieve-a-comment.md) - [Mark a comment as read](https://developers.telnyx.com/api-reference/phone-number-orders/mark-a-comment-as-read.md) ### Phone Number Block Orders - [List number block orders](https://developers.telnyx.com/api-reference/phone-number-block-orders/list-number-block-orders.md): Get a paginated list of number block orders. - [Create a number block order](https://developers.telnyx.com/api-reference/phone-number-block-orders/create-a-number-block-order.md): Creates a phone number block order. - [Retrieve a number block order](https://developers.telnyx.com/api-reference/phone-number-block-orders/retrieve-a-number-block-order.md): Get an existing phone number block order. ### Requirement Groups - [Update requirement group for a phone number order](https://developers.telnyx.com/api-reference/requirement-groups/update-requirement-group-for-a-phone-number-order.md) - [Update requirement group for a sub number order](https://developers.telnyx.com/api-reference/requirement-groups/update-requirement-group-for-a-sub-number-order.md) ### Advanced Number Orders - [List Advanced Orders](https://developers.telnyx.com/api-reference/advanced-number-orders/list-advanced-orders.md) - [Create Advanced Order](https://developers.telnyx.com/api-reference/advanced-number-orders/create-advanced-order.md) - [Update Advanced Order](https://developers.telnyx.com/api-reference/advanced-number-orders/update-advanced-order.md) - [Get Advanced Order](https://developers.telnyx.com/api-reference/advanced-number-orders/get-advanced-order.md) ### Inexplicit Number Orders - [List inexplicit number orders](https://developers.telnyx.com/api-reference/inexplicit-number-orders/list-inexplicit-number-orders.md): Get a paginated list of inexplicit number orders. - [Create an inexplicit number order](https://developers.telnyx.com/api-reference/inexplicit-number-orders/create-an-inexplicit-number-order.md): Create an inexplicit number order to programmatically purchase phone numbers without specifying exact numbers. - [Retrieve an inexplicit number order](https://developers.telnyx.com/api-reference/inexplicit-number-orders/retrieve-an-inexplicit-number-order.md): Get an existing inexplicit number order by ID. ### Callbacks - [Number Order Status Update](https://developers.telnyx.com/api-reference/callbacks/number-order-status-update.md) ### Phone Number Blocks Background Jobs - [Lists the phone number blocks jobs](https://developers.telnyx.com/api-reference/phone-number-blocks-background-jobs/lists-the-phone-number-blocks-jobs.md) - [Retrieves a phone number blocks job](https://developers.telnyx.com/api-reference/phone-number-blocks-background-jobs/retrieves-a-phone-number-blocks-job.md) - [Deletes all numbers associated with a phone number block](https://developers.telnyx.com/api-reference/phone-number-blocks-background-jobs/deletes-all-numbers-associated-with-a-phone-number-block.md): Creates a new background job to delete all the phone numbers associated with the given block. We will only consider the phone number block as deleted after all… ### Phone Number Configurations - [List phone numbers](https://developers.telnyx.com/api-reference/phone-number-configurations/list-phone-numbers.md) - [Retrieve a phone number](https://developers.telnyx.com/api-reference/phone-number-configurations/retrieve-a-phone-number.md) - [Update a phone number](https://developers.telnyx.com/api-reference/phone-number-configurations/update-a-phone-number.md) - [Delete a phone number](https://developers.telnyx.com/api-reference/phone-number-configurations/delete-a-phone-number.md) - [Change the bundle status for a phone number (set to being in a bundle or remove from a bundle)](https://developers.telnyx.com/api-reference/phone-number-configurations/change-the-bundle-status-for-a-phone-number-set-to-being-in-a-bundle-or-remove-from-a-bundle.md) - [Enable emergency for a phone number](https://developers.telnyx.com/api-reference/phone-number-configurations/enable-emergency-for-a-phone-number.md) - [Retrieve a phone number with voice settings](https://developers.telnyx.com/api-reference/phone-number-configurations/retrieve-a-phone-number-with-voice-settings.md) - [Update a phone number with voice settings](https://developers.telnyx.com/api-reference/phone-number-configurations/update-a-phone-number-with-voice-settings.md) - [Verify ownership of phone numbers](https://developers.telnyx.com/api-reference/phone-number-configurations/verify-ownership-of-phone-numbers.md): Verifies ownership of the provided phone numbers and returns a mapping of numbers to their IDs, plus a list of numbers not found in the account. - [Slim List phone numbers](https://developers.telnyx.com/api-reference/phone-number-configurations/slim-list-phone-numbers.md): List phone numbers, This endpoint is a lighter version of the /phone_numbers endpoint having higher performance and rate limit. - [List phone numbers with voice settings](https://developers.telnyx.com/api-reference/phone-number-configurations/list-phone-numbers-with-voice-settings.md) ### CSV Downloads - [List CSV downloads](https://developers.telnyx.com/api-reference/csv-downloads/list-csv-downloads.md) - [Create a CSV download](https://developers.telnyx.com/api-reference/csv-downloads/create-a-csv-download.md) - [Retrieve a CSV download](https://developers.telnyx.com/api-reference/csv-downloads/retrieve-a-csv-download.md) ### Bulk Phone Number Operations - [Lists the phone numbers jobs](https://developers.telnyx.com/api-reference/bulk-phone-number-operations/lists-the-phone-numbers-jobs.md) - [Retrieve a phone numbers job](https://developers.telnyx.com/api-reference/bulk-phone-number-operations/retrieve-a-phone-numbers-job.md) - [Delete a batch of numbers](https://developers.telnyx.com/api-reference/bulk-phone-number-operations/delete-a-batch-of-numbers.md): Creates a new background job to delete a batch of numbers. At most one thousand numbers can be updated per API call. - [Update the emergency settings from a batch of numbers](https://developers.telnyx.com/api-reference/bulk-phone-number-operations/update-the-emergency-settings-from-a-batch-of-numbers.md): Creates a background job to update the emergency settings of a collection of phone numbers. At most one thousand numbers can be updated per API call. - [Update a batch of numbers](https://developers.telnyx.com/api-reference/bulk-phone-number-operations/update-a-batch-of-numbers.md): Creates a new background job to update a batch of numbers. At most one thousand numbers can be updated per API call. At least one of the updateable fields must… ### Regulatory Requirements - [Retrieve regulatory requirements for a list of phone numbers](https://developers.telnyx.com/api-reference/regulatory-requirements/retrieve-regulatory-requirements-for-a-list-of-phone-numbers.md)