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). This file: https://developers.telnyx.com/development/llms/numbers-global-phone-numbers-llms-full-txt.md · Root index: https://developers.telnyx.com/llms.txt

Coverage

Getting started with Telnyx phone number APIs

Source: https://developers.telnyx.com/docs/numbers/phone-numbers/getting-started.md

Overview

The Telnyx Numbers API lets you search for available phone numbers, reserve them, and place orders — all programmatically. Below are the key concepts you need to understand before purchasing numbers.

Coverage

Telnyx sells phone numbers in 100+ countries across multiple phone number types (local, national, mobile, toll-free). To see a list of supported countries and number types, query the Get Country Coverage API. The response includes:

Countries and available phone number types within each country
Applicable phone number attributes
Whether the inventory coverage API (inventory_coverage=true) is supported

If inventory coverage is supported, use the Inventory Coverage API to assess how many numbers are available based on your search criteria.

Regulatory Requirements

Some countries require additional documentation before phone numbers can be activated — for example, proof of address or business registration. Requirement Resources

Feature	Description
Compliance Page	View regulatory requirements for all countries in the Telnyx Portal
Developer Guide	Guide discussing regulatory requirements in more detail, including relevant API requests.
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. You can filter by country, number type, city, area code, and features.

curl -X GET "https://api.telnyx.com/v2/available_phone_numbers?filter[country_code]=US&filter[phone_number_type]=local&filter[limit]=5" \
  -H "Authorization: Bearer $TELNYX_API_KEY"

For a deeper dive into search strategies, check out the Number Search Guide.

Reserve

Reserve phone numbers 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. Numbers in the order must come from a prior search.

curl -X POST https://api.telnyx.com/v2/number_orders \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_numbers": [
      {"phone_number": "+12025551234"}
    ]
  }'

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 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 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, search results may be limited.

Best Practices

When supported, use the inventory coverage API 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 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.
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, 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). 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).

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). 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 endpoint to search for phone numbers to purchase. See this guide 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 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.

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 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 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. 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 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, 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 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 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:

The search returns available phone numbers that you can purchase.
The search targets a region where Telnyx has no coverage, resulting in a 4xx response.
The request errors out due to a server issue (5xx) or a timeout.
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, developer guide here). 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.

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.

Create a requirement group that matches the “country” and “phone number type” of your Advanced Order.
Make a PATCH https://api.telnyx.com/v2/advanced_orders/:order_id/requirement_group request (API reference here). Use the requirement group id as the “requirement_group_id” value in the request body.
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) 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.

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 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, review the results, and then create 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 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 to create an order. Each ordering_group requires country_iso (US or CA), count_requested, and phone_number_type. Optionally include search filters 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: List all bulk orders with pagination support.
GET /v2/inexplicit_number_orders/{id}: 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}: Retrieve the parent number order.
GET /v2/sub_number_orders: List sub number orders.

From this point, follow the standard number ordering workflow to complete any remaining steps.

Webhook Notifications

You can configure webhook notifications to receive updates about your orders. Follow this support article 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: Get country coverage
Get coverage for a specific country: Get coverage for a specific country

Inventory Level

Create an inventory coverage request: 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: Searches the Telnyx inventory for available contiguous phone-number blocks. Results can be filtered by locality, country, national destination code, and number…
List available phone numbers: Searches the Telnyx inventory for available phone numbers. Filters support number patterns, location, number type, features, reservability, and other inventory…

numbers features

Retrieve the features for a list of numbers: Retrieve the features for a list of numbers

Phone Number Reservations

List number reservations: Gets a paginated list of phone number reservations.
Create a number reservation: Creates a Phone Number Reservation for multiple numbers.
Retrieve a number reservation: Gets a single phone number reservation.
Extend a number reservation: Extends reservation expiry time on all phone numbers.

Phone Number Orders

List number orders: Get a paginated list of number orders.
Create a number order: Creates a phone number order.
Retrieve a number order: Get an existing phone number order.
Update a number order: Updates a phone number order.
Retrieve a list of phone numbers associated to orders: Get a list of phone numbers associated to orders.
Retrieve a single phone number within a number order.: Get an existing phone number in number order.
Update requirements for a single phone number within a number order.: Updates requirements for a single phone number within a number order.
List sub number orders: Get a paginated list of sub number orders.
Retrieve a sub number order: Get an existing sub number order.
Update a sub number order’s requirements: Updates a sub number order.
Cancel a sub number order: Allows you to cancel a sub number order in ‘pending’ status.
Retrieve all comments: Returns comments associated with number-order records. Results can be filtered by record type and record ID and include pagination metadata.
Create a comment: Creates a comment associated with a supported number-order record. The response contains the created comment.
Retrieve a comment: Returns the comment identified by id, including its associated record and comment metadata.
Mark a comment as read: Marks the specified comment as read. The response contains the updated read state for the comment.
Create a sub number orders report: 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: Get the status and details of a sub number orders report.
Download a sub number orders report: Download the CSV file for a completed sub number orders report. The report status must be ‘success’ before the file can be downloaded.

Phone Number Block Orders

List number block orders: Get a paginated list of number block orders.
Create a number block order: Creates a phone number block order.
Retrieve a number block order: Get an existing phone number block order.

Requirement Groups

Update requirement group for a phone number order: Associates an existing requirement group with a phone number in a number order. The response contains the updated number-order phone-number details.
Update requirement group for a sub number order: Associates an existing requirement group with the specified sub number order. The response contains the updated sub number order requirement-group relationship.

Advanced Number Orders

List Advanced Orders: Returns the advanced number orders associated with the account. Each result includes the order configuration and its current state.
Create Advanced Order: Creates an advanced number order from the requested order configuration. The response contains the resulting advanced order and its initial state.
Update Advanced Order: Updates the requirement-group configuration for the specified advanced number order. The response contains the updated advanced order.
Get Advanced Order: Returns the advanced number order identified by order_id, including its configuration and current state.

Inexplicit Number Orders

List inexplicit number orders: Get a paginated list of inexplicit number orders.
Create an inexplicit number order: Create an inexplicit number order to programmatically purchase phone numbers without specifying exact numbers.
Retrieve an inexplicit number order: Get an existing inexplicit number order by ID.

Callbacks

Number Order Status Update

Phone Number Blocks Background Jobs

Lists the phone number blocks jobs: Returns background jobs that operate on phone-number blocks. Results can be filtered by job type and status, sorted by creation time, and include pagination me…
Retrieves a phone number blocks job: Returns the status and details of the phone-number-block background job identified by id.
Deletes all numbers associated with a phone number block: 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: Returns phone numbers associated with the account. Results support pagination, sorting, and filters for number attributes, status, source, connections, billing…
Delete a phone number: Deletes the specified phone number from the account. The response contains the phone number’s final deleted representation.
Retrieve a phone number: Returns the detailed configuration and current state of the phone number identified by id.
Update a phone number: Updates the configurable settings of the specified phone number. The response contains the complete updated phone-number representation.
Change the bundle status for a phone number (set to being in a bundle or remove from a bundle): Adds the specified phone number to a bundle or removes it from a bundle according to the requested status change. The response contains the phone number with i…
Enable emergency for a phone number: Associates emergency-service settings with the specified phone number. The operation returns the updated phone-number configuration when completed immediately…
Retrieve a phone number with voice settings: Returns the specified phone number together with its current voice configuration.
Update a phone number with voice settings: Updates the voice configuration for the specified phone number. The response contains the phone number with its updated voice settings.
Verify ownership of phone numbers: 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: 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: Returns account phone numbers together with their voice settings. Results support pagination, sorting, and filters for number, connection name, customer refere…

CSV Downloads

List CSV downloads: Returns CSV export jobs created for account phone numbers, including each export’s current status and pagination metadata.
Create a CSV download: Starts generation of a CSV export for phone numbers matching the supplied filters. The csv_format parameter selects the output format, and the response conta…
Retrieve a CSV download: Returns the current status and download details for the CSV export identified by id.

Bulk Phone Number Operations

Lists the phone numbers jobs: Returns background jobs that operate on phone numbers. Results can be filtered by job type and sorted by creation time, and include pagination metadata.
Retrieve a phone numbers job: Returns the status and details of the phone-number background job identified by id.
Delete a batch of numbers: 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: 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: 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: Retrieve the regulatory requirements that apply to a list of phone numbers.

​Telnyx Numbers: Global Phone Numbers — Full Documentation

​Coverage

​Getting started with Telnyx phone number APIs

​Overview

​Coverage

​Regulatory Requirements

​Search

​Reserve

​Order

​Advanced Order

​Searching

​Number search

​Constraints

​Best Practices

​Filter for specific phone numbers

​Required Filters

​Standard Filters

​Advanced Filters

​Ordering

​Number reservations

​Overview

​Constraints:

​Reservation Flow

​Step 1: Search for reservable phone numbers

​Step 2: Create a reservation

​List all reservations

​Extend a reservation

​Number orders

​Ordering Flow

​Step 1: Search for phone numbers.

​Step 2: Create an order

​Step 3: Regulatory Requirements

​Step 4: Handling Regulatory Requirement Rejections

​“Number Order” vs “Sub Number Order”

​Order Statuses

​Deadline + Auto Cancellation

​Webhook notifications

​Advanced Orders

​Overview

​Constraints

​Advanced Order Statuses

​How it works

​1. Search for phone numbers to purchase

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

​3. Add regulatory requirements to an Advanced Order

​4. Finish the number ordering process

​Comments

​Notifications

​Webhook events

​Bulk orders

​Overview

​Constraints

​Ordering Groups

​Order Statuses

​How It Works

​Step 1: Create a bulk order

​Step 2: Monitor order status

​Step 3: Access the created number orders

​Webhook Notifications

​API Reference (Global Phone Numbers)

​Country Coverage

​Inventory Level

​Phone Number Search

​numbers features

​Phone Number Reservations

​Phone Number Orders

​Phone Number Block Orders

​Requirement Groups

​Advanced Number Orders

​Inexplicit Number Orders

​Callbacks

​Phone Number Blocks Background Jobs

​Phone Number Configurations

​CSV Downloads

​Bulk Phone Number Operations

​Regulatory Requirements

Telnyx Numbers: Global Phone Numbers — Full Documentation

Coverage

Getting started with Telnyx phone number APIs

Overview

Coverage

Regulatory Requirements

Search

Reserve

Order

Advanced Order

Searching

Number search

Constraints

Best Practices

Filter for specific phone numbers

Required Filters

Standard Filters

Advanced Filters

Ordering

Number reservations

Overview

Constraints:

Reservation Flow

Step 1: Search for reservable phone numbers

Step 2: Create a reservation

List all reservations

Extend a reservation

Number orders

Ordering Flow

Step 1: Search for phone numbers.

Step 2: Create an order

Step 3: Regulatory Requirements

Step 4: Handling Regulatory Requirement Rejections

“Number Order” vs “Sub Number Order”

Order Statuses

Deadline + Auto Cancellation

Webhook notifications

Advanced Orders

Overview

Constraints

Advanced Order Statuses

How it works

1. Search for phone numbers to purchase

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

3. Add regulatory requirements to an Advanced Order

4. Finish the number ordering process

Comments

Notifications

Webhook events

Bulk orders

Overview

Constraints

Ordering Groups

Order Statuses

How It Works

Step 1: Create a bulk order

Step 2: Monitor order status

Step 3: Access the created number orders

Webhook Notifications

API Reference (Global Phone Numbers)

Country Coverage

Inventory Level

Phone Number Search

numbers features

Phone Number Reservations

Phone Number Orders

Phone Number Block Orders

Requirement Groups

Advanced Number Orders

Inexplicit Number Orders

Callbacks

Phone Number Blocks Background Jobs

Phone Number Configurations

CSV Downloads

Bulk Phone Number Operations

Regulatory Requirements