Telnyx Numbers — Full Documentation

Phone number search and ordering, porting, regulatory requirements, and identity. Complete page content for the Numbers section of the Telnyx developer docs (https://developers.telnyx.com). Root index: https://developers.telnyx.com/llms.txt · Lightweight index for this section: https://developers.telnyx.com/development/llms/numbers-llms-txt.md

Global Phone Numbers

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

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.

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.

Porting

Port in orders

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

Overview

Port-in orders allow you to transfer existing phone numbers from another carrier to Telnyx. The porting process involves creating a draft order, providing required information and documents, and submitting the order for processing with the losing carrier. Port orders are processed asynchronously through coordination between Telnyx and the losing carrier. Processing times vary based on carrier, country, and phone number type—ranging from same-day for FastPort-eligible numbers to several weeks for international ports. For general information about the porting process, timelines, and international requirements, see the porting support articles.

Constraints

Phone numbers must pass a portability check before creating a port order. Non-portable numbers will result in API errors.
Port orders may be automatically split into multiple orders based on country, number type, SPID (for US/CA), and FastPort eligibility.
Each split order must be updated and submitted independently.
A Letter of Authorization (LOA) and recent invoice are required for most port orders.
Requested FOC dates are not guaranteed—the losing carrier determines the actual activation date.

Order splitting

When you create a port order with multiple phone numbers, the API may split them into separate orders. Numbers are grouped based on:

Country: Numbers from different countries are split into separate orders.
Number type: Local, toll-free, and mobile numbers are processed separately.
SPID: For US and CA numbers, numbers with different Service Provider IDs are split.
FastPort eligibility: FastPort-eligible numbers are separated from standard port orders.

If your order is split, the API returns multiple port order IDs. You must complete and submit each order individually.

How it works

Step 1: Check portability

Use the Portability check endpoint to verify your numbers can be ported to Telnyx before creating an order. Phone numbers must be submitted in E.164 format. The response indicates whether each number is portable and includes additional details like fast_portable eligibility and messaging_capable status. If a number is not portable, the not_portable_reason field explains why.

Step 2: Create a draft port order

Use the Create porting order endpoint to create a draft order with your phone numbers. The API validates the numbers and may split them into multiple orders. Each order is created in draft status, allowing you to add required information before submission.

Step 3: Fulfill the porting order

Use the Edit porting order endpoint to provide the required information:

End user information: The name and account details of the current account holder with the losing carrier.
Service address: The address associated with the phone numbers being ported.
Regulatory requirements: Documents and information required for the port, such as a Letter of Authorization (LOA) and recent invoice. See the port-in requirements guide for details.
Phone number configuration: Optionally assign a connection_id, messaging_profile_id, or emergency_address_id to apply settings to all ported numbers.
FOC date: Select your requested firm order commitment (FOC) date—the date your numbers will port to Telnyx. See the allowed FOC dates guide for details on retrieving available windows and setting your preferred date.

Step 4: Submit the port order

Use the Submit porting order endpoint to submit your order. The order transitions from draft to in-process status. Telnyx validates the submission and coordinates with the losing carrier to complete the port.

Step 5: Monitor order progress

Track your order status using the Retrieve porting order endpoint or configure webhooks to receive status change notifications. If the order enters exception status, check the order comments for details about the rejection. Update the required information and resubmit.

Notifications

Configure webhooks to receive real-time updates about your port orders. The porting_order.status_changed event fires whenever an order transitions to a new status. For more information about configuring notifications and viewing event history, see the port-in notifications guide and port-in events guide.

Comments

Comments allow you to communicate directly with Telnyx Porting Operations during the porting process. Use the Create comment endpoint to send messages or respond to requests from the porting team. Monitor your port orders for new comments using the List comments endpoint. Porting Operations may add comments to request additional information or provide updates about your order. Subscribe to the porting_order.new_comment webhook event to receive notifications when new comments are added.

Additional resources

Port-in requirements - View and fulfill regulatory requirements on your port orders.
Allowed FOC dates - Request and set a specific date for your port order to complete.
On-demand activations - Take control of your port order with FastPort on-demand activations.
Cancel port order - Cancel a port order before it completes.

Port-in requirements

Source: https://developers.telnyx.com/docs/numbers/porting/port-in-requirements.md

Overview

All port-in orders have regulatory requirements that must be fulfilled before the port can be completed. These requirements vary based on the country and phone number type you are porting.

How it works

Step 1: View requirements on your port order

When you create a port order, the requirements array is automatically populated based on the country and phone number type being ported. Each requirement includes a requirement_type_id that identifies what information is needed. Use the GET /v2/porting_orders/{id}/requirements endpoint to view detailed information about all requirements on your port order, including descriptions and acceptance criteria.

Step 2: Fulfill requirements

To fulfill a requirement, submit the appropriate field_value for each requirement_type_id using the PATCH /v2/porting_orders/{id} endpoint. The value you provide depends on the requirement type:

Document: Provide a document ID from the Documents API.
Textual: Provide a string value that meets the acceptance criteria.
Address: Provide an address ID from the Addresses API.

For detailed fulfillment instructions for each type, see the regulatory requirements guide.

Requirement statuses

Each requirement on a port order has a status that indicates its current state:

Status	Description
`requirement-info-pending`	Awaiting user submission. You need to provide information to fulfill the requirement.
`requirement-info-under-review`	Information has been submitted and is awaiting review by Telnyx Porting Operations.
`requirement-info-exception`	The submitted information does not meet the acceptance criteria. You need to resubmit with corrected information.
`approved`	The requirement has been reviewed and validated by Telnyx Porting Operations.

Order-level requirements status

For a high-level view of whether all requirements have been fulfilled and approved, check the requirements_status field on the port order:

true: All requirements on the port order have been fulfilled and approved.
false: One or more requirements have not been fulfilled or have not been approved yet.

Use the GET /v2/porting_orders/{id} endpoint to check this status.

Allowed FOC dates

Source: https://developers.telnyx.com/docs/numbers/porting/allowed-foc-dates.md

Overview

The firm order commitment (FOC) date is when the losing carrier agrees to release phone numbers to Telnyx. This is the date your port will actually complete and your numbers will become active on your Telnyx account. When creating or updating a port order, you can request a specific FOC date using the foc_datetime_requested field. This gives you control over when your numbers port, allowing you to coordinate the transition with your business operations. Once Telnyx receives FOC confirmation from the losing carrier, the order transitions to foc-date-confirmed status. The foc_datetime_actual field then reflects the confirmed date, which may differ from your requested date depending on carrier availability.

Constraints

Requested FOC dates are not guaranteed. The losing carrier ultimately determines the actual FOC date.
The requested date and time must fall within one of the allowed FOC windows returned by the API.
FOC windows vary based on the losing carrier and the phone numbers in your order.

How it works

Step 1: Retrieve allowed FOC windows

Use the List allowed FOC dates endpoint to view the available FOC windows for your port order. The response contains an array of allowed windows, each with start_time and end_time fields indicating the valid date and time range. All times are in UTC format. For example, a window with start_time of 2024-03-15T15:00:00Z and end_time of 2024-03-15T23:00:00Z means you can request any time between 15:00 and 23:00 UTC on March 15th.

Step 2: Set your requested FOC date

Use the Edit porting order endpoint to set your preferred FOC date. Update the activation_settings.foc_datetime_requested field with a timestamp that falls within one of the allowed windows. The timestamp must be in ISO 8601 format (for example, 2024-03-15T15:00:00Z).

Step 3: Monitor FOC confirmation

After submitting your port order, Telnyx works with the losing carrier to confirm the FOC date. When confirmed, the order status changes to foc-date-confirmed and the foc_datetime_actual field updates with the confirmed date and time. Monitor your order status through the Retrieve porting order endpoint or configure webhooks to receive notifications when the status changes.

Notifications

You can receive webhook notifications when the port order status changes. Configure webhooks to receive porting_order.status_changed events when the order transitions to foc-date-confirmed status. For more information about porting webhooks, see the port-in events guide.

Cancel port order

Source: https://developers.telnyx.com/docs/numbers/porting/cancel-port-order.md

Overview

Canceling a port order allows you to stop a port-in request before it completes. This is useful when business requirements change, the port was submitted in error, or you no longer need to transfer the phone numbers to Telnyx. When you cancel a port order, it first transitions to a cancel-pending status while the Porting Operations team reviews and processes the cancellation request. Once processed, the order moves to cancelled status and the port-in will not proceed.

Constraints

You cannot cancel a port order via the API within 48 hours of the FOC (Firm Order Commitment) date/time. If you need to cancel within this window, contact Telnyx support directly.
Cancellation requests require review by the Porting Operations team before taking effect.
Once a port order reaches cancelled status, it cannot be reactivated. You would need to submit a new port order.

Cancellation statuses

When you cancel a port order, it progresses through the following statuses:

Status	Description
`cancel-pending`	The cancellation request has been submitted and is awaiting review by the Porting Operations team.
`cancelled`	The port order has been successfully cancelled and will not proceed.

How it works

Step 1: Cancel the port order

Use the POST /v2/porting_orders/{id}/actions/cancel endpoint to request cancellation of a port order. Provide the port order ID in the request path. The port order will transition to cancel-pending status upon successful submission. If the port order’s FOC date is within 48 hours, the API will return an error. In this case, contact Telnyx support to request cancellation.

Step 2: Monitor cancellation status

You can check the status of the cancellation using the GET /v2/porting_orders/{id} endpoint. The port order will remain in cancel-pending status until the Porting Operations team processes the request. Once complete, the status will change to cancelled.

Notifications

You can receive webhook notifications when the port order status changes. Configure webhooks to receive porting_order.status_changed events when the order transitions to cancel-pending and cancelled statuses. For more information about porting webhooks, see the port-in events guide.

On-demand activations

Source: https://developers.telnyx.com/docs/numbers/porting/on-demand-activations.md

Overview

On-demand activations give you control over when your ported phone numbers activate. Rather than having numbers activate automatically at a carrier-assigned time, you can trigger the activation yourself within a designated window on the FOC (Firm Order Commitment) date. This differs from scheduled activations where numbers automatically port at the exact FOC date and time assigned by the carrier. With on-demand activation, you choose the precise moment within the activation window that works best for your business operations. If you don’t initiate the activation during the window, the numbers will automatically port at the end of the window. This ensures your port order completes even if you miss the manual activation opportunity.

Constraints

On-demand activation is only available for orders where fast_port_eligible is true.
Currently available for phone numbers in the US and Canada only.
You can only initiate activation after the order reaches foc-date-confirmed status.
Activation must occur within the designated activation window on the FOC date.

Activation windows

Each country has a specific window during which you can initiate on-demand activation. The window defines the earliest and latest times you can trigger the port.

Country	Window start	Window end	Duration
US	6:00 AM CT	8:00 PM CT	14 hours
Canada	8:00 AM CT	3:00 PM CT	7 hours

When your order reaches foc-date-confirmed status, an activation job is created. The activation_windows array in the activation job response shows the exact start and end times for your specific order. The activate_at field indicates when the port will occur. By default, this is set to the end of the activation window. When you initiate on-demand activation, this field updates to reflect when you triggered the request.

Activation job statuses

Each activation job has a status indicating its current state:

Status	Description
`created`	The activation job exists and is waiting for the activation window to open.
`in-process`	The activation has been initiated and numbers are being ported.
`completed`	The activation finished successfully and numbers have been ported.

How it works

Step 1: Enable on-demand activation

By default, all porting orders use scheduled activation (activation_type: scheduled). To enable on-demand activation, update the order’s activation settings using the Edit porting order endpoint. Set activation_settings.activation_type to on-demand. The order must have fast_port_eligible set to true for this to succeed.

Step 2: View the activation window

Once your order reaches foc-date-confirmed status, retrieve the activation job to see your activation window. Use the List porting activation jobs endpoint to view the activation_windows array containing your window’s start_at and end_at times.

Step 3: Initiate activation

When the FOC date arrives and you’re within the activation window, trigger the port using the Activate porting order endpoint. The activate_at field updates to reflect the time you submitted the request, and the activation process begins.

Step 4: Monitor activation progress

Track the activation job status to monitor progress. Use the List porting activation jobs endpoint or Retrieve a porting activation job endpoint to check the current status. The job progresses from created to in-process to completed. Once the status reaches completed, your numbers have finished porting and are active on your Telnyx account. For real-time updates, configure porting notifications to receive webhooks as the activation progresses.

Port-in order notifications

Source: https://developers.telnyx.com/docs/numbers/porting/port-in-notifications.md

We understand the importance of being able to track the progress and status of your port orders. That is why we offer port-in notifications for the following events:

Port order status changes
New comments
Split port orders
Messaging activation
Deleted “draft” porting orders

Notifications can be emitted to either email or webhook addresses. The following sections will cover how to enable notification settings for port-in events and provide example responses to various webhook notification events.

How to setup notifications via the Portal for all port orders (email and webhook)

If you are adding port-in notification settings in the portal, they will apply for all port orders that you create. Here is how to get started:

Sign in to the Telnyx Portal
Go to your Account Settings and click on the Advanced Features section. Then select Notifications.
Click on the New Profile button to create a new Notification Profile
Click on the New Channel button to specify which email or webhook URL to send notifications to. Add as many notification channels as you would like!
Click on the New Setting button, select Port In Notifications and select the profile and channel that you would like Telnyx to send port-in notifications to.

If you have further questions, check out this support article or contact our customer support team.

How to setup notifications on specific port orders (webhook only)

If your use case or integration requires each port order to have its own webhook URL for port-in notifications, you can specify a unique URL as the value for the webhook_url parameter in the port order form. This will allow you to receive notifications of updates to the specified order at the webhook URL you provided. An example PATCH request is shown below:

curl --location --request PATCH 'https://api.telnyx.com/v2/porting_orders/{{id}}' \
--header 'Authorization: Bearer [REDACTED] \
--header 'Content-Type: application/json' \
--data-raw '{
    "webhook_url": "https://webhook.site/98e5e9e2-4921-4a64-b3c8-da0c6ce760f3"
}'

Example webhook notification events:

Transition to `in-process` status

{
  "data": {
    "event_type": "porting_order.status_changed",
    "id": "8179f546-d479-42be-822b-8c78e1e89a59",
    "occurred_at": "2023-01-11T16:08:31.804886Z",
    "payload": {
      "customer_reference": "1-alpha-2-bravo-3-charlie",
      "id": "f6e10519-4664-4119-bb03-bbe73cf26ed3",
      "status": {
        "details": [],
        "value": "in-process"
      },
      "support_key": "sr_ac8c24",
      "updated_at": "2023-01-11T16:08:31.804886Z",
      "webhook_url": "https://example.com/porting_webhooks"
    },
    "record_type": "event"
  },
  "meta": {
    "attempt": 1,
    "delivered_to": "https://example.com/porting_webhooks"
  }
}

Transition to `submitted` status

{
  "data": {
    "event_type": "porting_order.status_changed",
    "id": "12ae614e-ed37-4a19-9fe3-2b69bf33d429",
    "occurred_at": "2021-01-19T19:52:13.874635Z",
    "payload": {
      "customer_reference": "1-alpha-2-bravo-3-charlie",
      "id": "3594c6c3-51a7-4306-b715-ca3765f13464",
      "status": {
        "details": [],
        "value": "submitted"
      },
      "support_key": "sr_98f022",
      "updated_at": "2021-03-19T19:52:13+00:00",
      "webhook_url": "https://example.com/porting_webhooks"
    },
    "record_type": "event"
  },
  "meta": {
    "attempt": 1,
    "delivered_to": "https://example.com/porting_webhooks"
  }
}

Transition to `exception` status

A port-in order can have multiple underlying exception reasons. When resolved, the order will transition back to a submitted status (and you will receive the same webhook outlined in the previous section).

{
  "data": {
    "event_type": "porting_order.status_changed",
    "id": "72322cb3-b6c6-46a4-a571-21a759c02da0",
    "occurred_at": "2021-01-19T19:51:37.844234Z",
    "payload": {
      "customer_reference": "1-alpha-2-bravo-3-charlie",
      "id": "3594c6c3-51a7-4306-b715-ca3765f13464",
      "status": {
        "details": [
          {
            "code": "ACCOUNT_NUMBER_MISMATCH",
            "description": "Account number does not match that on the CSR"
          },
          {
            "code": "PORTING_ORDER_SPLIT_REQUIRED",
            "description": "The OSP requires this Porting Order to be split map_exception_detail and submitted as separate orders"
          },
          {
            "code": "LOA_ILLEGIBLE",
            "description": "The LOA is illegible"
          }
        ],
        "value": "exception"
      },
      "support_key": "sr_98f022",
      "updated_at": "2021-03-19T19:51:37+00:00",
      "webhook_url": "https://example.com/porting_webhooks"
    },
    "record_type": "event"
  },
  "meta": {
    "attempt": 1,
    "delivered_to": "https://example.com/porting_webhooks"
  }
}

Transition to `foc-date-confirmed` status

{
  "data": {
    "event_type": "porting_order.status_changed",
    "id": "80227461-b684-4e89-a1a9-5055a2b4d8ef",
    "occurred_at": "2021-03-19T19:48:58.261079Z",
    "payload": {
      "customer_reference": "1-alpha-2-bravo-3-charlie",
      "id": "3594c6c3-51a7-4306-b715-ca3765f13464",
      "status": {
        "details": [],
        "value": "foc-date-confirmed"
      },
      "support_key": "sr_98f022",
      "updated_at": "2021-03-19T19:48:57+00:00",
      "webhook_url": "https://example.com/porting_webhooks"
    },
    "record_type": "event"
  },
  "meta": {
    "attempt": 1,
    "delivered_to": "https://example.com/porting_webhooks"
  }
}

Transition to `ported` status

{
  "data": {
    "event_type": "porting_order.status_changed",
    "id": "334e12a2-a016-489e-a2b6-7abb46637327",
    "occurred_at": "2021-03-19T19:48:58.261079Z",
    "payload": {
      "customer_reference": "1-alpha-2-bravo-3-charlie",
      "id": "3594c6c3-51a7-4306-b715-ca3765f13464",
      "status": {
        "details": [],
        "value": "ported"
      },
      "support_key": "sr_98f022",
      "updated_at": "2021-03-19T19:48:57+00:00",
      "webhook_url": "https://example.com/porting_webhooks"
    },
    "record_type": "event"
  },
  "meta": {
    "attempt": 1,
    "delivered_to": "https://example.com/porting_webhooks"
  }
}

Transition to `cancel-pending` status

{
  "data": {
    "event_type": "porting_order.status_changed",
    "id": "4f0c225d-3892-4e0e-9524-7625dfc20b19",
    "occurred_at": "2022-04-11T15:50:53.869432Z",
    "payload": {
      "customer_reference": "Test1234",
      "id": "f17074cb-72ee-48b4-bb45-64894e756f01",
      "status": {
        "details": [],
        "value": "cancel-pending"
      },
      "support_key": "sr_602ae7",
      "updated_at": "2022-04-11T15:50:52+00:00",
      "webhook_url": "https://example.com/porting_webhooks"
    },
    "record_type": "event"
  },
  "meta": {
    "attempt": 1,
    "delivered_to": "https://example.com/porting_webhooks"
  }
}

Transition to `cancelled` status

{
  "data": {
    "event_type": "porting_order.status_changed",
    "id": "6cac3a83-dc30-45a9-ab51-32e1882f4d04",
    "occurred_at": "2022-04-11T15:52:52.596025Z",
    "payload": {
      "customer_reference": "Test1234",
      "id": "f17074cb-72ee-48b4-bb45-64894e756f01",
      "status": {
        "details": [],
        "value": "cancelled"
      },
      "support_key": "sr_602ae7",
      "updated_at": "2022-04-11T15:52:47+00:00",
      "webhook_url": "https://example.com/porting_webhooks"
    },
    "record_type": "event"
  },
  "meta": {
    "attempt": 1,
    "delivered_to": "https://example.com/porting_webhooks"
  }
}

New Comment

{
  "data": {
    "event_type": "porting_order.new_comment",
    "id": "6cafaed2-05f4-4791-9bcf-2392a0c912ef",
    "occurred_at": "2021-11-04T17:37:43.145988Z",
    "payload": {
      "comment": {
        "body": "Testing Webhooks 123",
        "id": "ca4b9cf6-d840-4ba9-ba38-95f4bc971164",
        "inserted_at": "2021-11-04T17:37:42Z",
        "user_id": null,
        "user_type": "admin"
      },
      "porting_order_id": "b3d55519-25c8-4af4-a50a-c92a9ddf7da4",
      "support_key": "sr_acdabe"
    },
    "record_type": "event"
  },
  "meta": {
    "attempt": 1,
    "delivered_to": "https://example.com/porting_webhooks"
  }
}

Split port-in order

You will receive one webhook for each number that is split from a port order and added to another port order. For example, if you originally submitted a port order with 5 numbers, and 3 numbers were split away from the original port order, then you would receive 3 split port order event notifications.

{
  "data": {
    "event_type": "porting_order.split",
    "id": "a98be460-2d1e-42b7-8c0d-d516c352efd2",
    "occurred_at": "2021-11-15T19:37:37.131727Z",
    "payload": {
      "from": {
        "id": "a6efe074-0a3a-4522-8512-d0e004cf6c7d"
      },
      "to": {
        "id": "ef245340-da3d-4212-8769-1fa7672a675f"
      }
    },
    "record_type": "event"
  },
  "meta": {
    "attempt": 1,
    "delivered_to": "https://example.com/porting_webhooks"
  }
}

Messaging activation

We recently introduced a new messaging activation feature to the V2 porting order API. Enabling this feature for your port order will make you eligible to receive the following webhook events. If there is an issue with the messaging activation when the phone numbers port in, then you will receive the following webhook:

{
  "id": "626110d0-fab6-4a13-9183-3b331c41ccac",
  "event_type": "porting_order.messaging_changed",
  "occurred_at": "2022-01-01T00:00:00Z",
  "urls": ["https://testing.com/callback"],
  "organization_id": "dbdbc891-dc82-4c39-b9a1-e51e830c4352",
  "format": "v2",
  "payload": {
    "id": "ce2f4509-d166-4834-a0b9-e3ecb469a537",
    "customer_reference": "my_ref_001",
    "messaging": {
      "messaging_capable": true,
      "enable_messaging": true,
      "messaging_port_status": "exception"
    },
    "support_key": "sr_abc123"
  }
}

Once Telnyx validates that messaging successfully ported for all phone numbers on the port order, then you will receive the following webhook:

{
  "id": "626110d0-fab6-4a13-9183-3b331c41ccac",
  "event_type": "porting_order.messaging_changed",
  "occurred_at": "2022-01-01T00:00:00Z",
  "urls": ["https://testing.com/callback"],
  "organization_id": "dbdbc891-dc82-4c39-b9a1-e51e830c4352",
  "format": "v2",
  "payload": {
    "id": "ce2f4509-d166-4834-a0b9-e3ecb469a537",
    "customer_reference": "my_ref_001",
    "messaging": {
      "messaging_capable": true,
      "enable_messaging": true,
      "messaging_port_status": "ported"
    },
    "support_key": "sr_abc123"
  }
}

Porting order deletion

A draft porting order may be deleted in two ways:

The user issues a DELETE /porting_orders/{id} API request
The draft porting order is deleted automatically when it fails to be submitted within 30 days

In either case, Telnyx will emit a webhook notification to communicate that the draft porting order has been deleted. An example of this webhook notification is shown below:

{
      "id": "4da7b0e3-1a3c-4111-8335-dc436f6a0a00",
      "event_type": "porting_order.deleted",
      "occurred_at": "2023-01-01T00:00:00Z",
      "urls": ["https://example.com/webhook"],
      "organization_id": "dbdbc891-dc82-4c39-b9a1-e51e830c4352",
      "format": "v2",
      "payload": {
            "id": "74cc03c8-ab01-4887-bc31-9563e482d1e3",
            "customer_reference": "my_ref_123",
            "deleted_at": "2023-01-01T00:00:00Z"
      }
}

Port-in events

Source: https://developers.telnyx.com/docs/numbers/porting/port-in-events.md

Overview

Port-in events provide a detailed record of everything that happens during the port-in process. Each time a status changes, a comment is added, or an order is split, the system creates an event that you can query and track. This differs from port-in notifications, which push updates to your webhook or email as they occur. The Events API gives you on-demand access to view your complete event history and republish notifications for specific events if needed. With the Port-in Events API, you can:

View all events across your port-in orders.
Filter events by port-in order, event type, or date range.
Republish notifications for specific events to your configured webhook or email.

Event types

The following event types are generated during the port-in lifecycle:

Event type	Description
`porting_order.status_changed`	The port-in order transitioned to a new status.
`porting_order.new_comment`	A new comment was added to the port-in order.
`porting_order.split`	One or more phone numbers were split into a separate order.
`porting_order.messaging_changed`	The messaging activation status changed for the port-in order.
`porting_order.deleted`	A draft port-in order was deleted.

How it works

Step 1: List port-in events

Use the GET /v2/porting/events endpoint to retrieve a list of events for your port-in orders. You can filter results by porting_order_id to view events for a specific order, or retrieve all events across your account with pagination support.

Step 2: Republish event notifications

If you need to resend notifications for a specific event, use the POST /v2/porting/events/{id}/republish endpoint where {id} is the event ID. This endpoint republishes notifications only to channels you are currently subscribed to. To configure your notification settings, see how to set up port-in notifications. Republishing an event resends the notifications but does not create a new event in the system. Email notifications may take a few minutes to be delivered.

Porting additional steps

Source: https://developers.telnyx.com/docs/numbers/porting/porting-additional-steps.md

Overview

After you create and populate a porting order, Telnyx may require additional steps depending on the phone numbers being ported and the details provided. These steps must be completed before you can submit the order. Additional steps differ from supplemental port order requirements, which cover documents and textual information needed for specific countries or number types. Additional steps involve actions or decisions that affect other phone numbers on your losing carrier’s account.

Checking for additional steps

The additional_steps array on a porting order indicates whether any additional steps are required.

Value	Meaning
`[]` (empty array)	No additional steps required. You can proceed with submission.
`["associated_phone_numbers"]`	You must provide a list of phone numbers on your losing carrier’s account that are not porting to Telnyx, and specify whether each should remain active or be deactivated after the port completes.

Retrieve the porting order using the GET /v2/porting_orders/{id} endpoint and check the additional_steps field in the response.

Associated phone numbers

This additional step applies to partial ports of GB local phone numbers. When porting only some phone numbers from an account, you must specify what happens to the remaining phone numbers on the losing carrier’s account.

When this step is required

The associated_phone_numbers step appears when both conditions are met:

The porting order is for GB local phone numbers.
The port_type is set to partial_port.

How it works

You must provide a list of phone numbers on your losing carrier’s account that are not being ported to Telnyx. For each phone number or range, you must indicate one of two outcomes:

Keep: The phone number remains active with the losing carrier after the port completes.
Disconnect: The phone number is disconnected from the losing carrier after the port completes.

If the billing telephone number (BTN) is included in the port, all remaining number ranges can only be disconnected.

Completing this step

Use the POST /v2/porting_orders/{id}/associated_phone_numbers endpoint to specify ranges of phone numbers and their intended outcome (keep or disconnect). You can associate multiple number ranges by sending separate requests for each range. The phone numbers you specify in this step are not being ported to Telnyx. This endpoint communicates what should happen to other phone numbers on the losing carrier’s account. Without this information, the losing carrier will reject the porting order.

Managing associated phone numbers

You can manage the phone numbers associated with your porting order using these endpoints:

Action	Endpoint
List associated phone numbers	GET /v2/porting_orders/{id}/associated_phone_numbers
Remove an associated phone number	DELETE /v2/porting_orders/{id}/associated_phone_numbers/{associated_phone_number_id}

Extensions

Source: https://developers.telnyx.com/docs/numbers/porting/extensions.md

Overview

Phone number extensions allow multiple phone lines to branch off from a single direct inward dialing (DID) number or main line. This setup is common in offices or call centers where individual desks or employees need unique extensions. The system has two components:

Route number: The primary phone number (also called the “main” number) that serves as the gateway for incoming calls before they are directed to specific extensions.
Extended numbers: Short digit sequences appended to the route number that connect callers directly to specific endpoints like departments or individuals.

For example, if the route number is +49 20 12345678, extensions might include +49 20 123456780 or +49 20 1234567806. When porting extended numbers, you first create a porting order with the route number, then attach the extensions to that order before submission.

Constraints

Extended number porting is currently only available for German port orders.
Extensions can only be added while the porting order is in draft, in-process, or exception status.
The maximum extension range is 0 to 999.
Activation ranges must be equal to or a subset of the extension range.
Activation ranges cannot overlap.

Extension range and activation ranges

Extensions are created in blocks defined by two parameters:

extension_range: Represents the full range of extensions available for the route number. This typically covers 10 numbers (0-9), 100 numbers (0-99), or 1000 numbers (0-999). All extensions within this range will port with the route number.
activation_ranges: Specifies which extensions within the extension_range should be active immediately upon port completion. Extensions not included in activation_ranges will port but remain inactive on your account.

For example, if your route number is +49 20 12345678 and you want to activate only extension +49 20 123456784:

Set extension_range to 0-9 (covering +49 20 123456780 through +49 20 123456789).
Set activation_ranges to 4-4 (activating only +49 20 123456784).

For multiple non-contiguous extensions like +49 20 1234567804, +49 20 1234567819, +49 20 1234567820, and +49 20 1234567842:

Set extension_range to 0-99.
Set activation_ranges to include 4-4, 19-20, and 42-42.

How it works

Step 1: Create a porting order with the route number

Create a porting order that includes the route number (the main DID). Do not include the extended numbers in the initial order.

Step 2: Retrieve the porting phone number ID

Use the List all porting phone numbers endpoint to retrieve the porting_phone_number_id for your route number. You will need this ID to attach extensions.

Step 3: Add extensions to the porting order

Use the Create a phone number extension endpoint to attach extensions to your porting order. Provide the porting_phone_number_id, extension_range, and activation_ranges in your request.

Step 4: Submit the porting order

Once extensions are attached, submit your porting order through the standard porting workflow. The route number and all extensions within the extension_range will port together.

Manage extensions

View extensions

The route number appears in the List all porting phone numbers response, but extended numbers do not. To view extensions attached to a porting order, use the List all phone number extensions endpoint.

Delete extensions

To remove extensions from a porting order before submission, use the Delete a phone number extension endpoint. The order must be in draft, in-process, or exception status.

Messaging + porting

Source: https://developers.telnyx.com/docs/numbers/porting/messaging-porting.md

Overview

For local and toll-free phone numbers in the US and Canada, porting voice and porting messaging are two separate processes. A porting order transitioning to ported status indicates that voice has ported to Telnyx, but this status does not reflect the state of messaging. Messaging routing is controlled by a NetNumber ID (NNID), which identifies the provider that owns SMS routing for a telephone number. At the FOC date and time, the losing carrier is expected to release the NNID so messaging routes through the winning carrier. In most cases, both voice and messaging port simultaneously. However, if the losing carrier fails to release the NNID, messaging continues to route through them even after voice has ported. This can occur due to:

Internal system errors or delays at the losing carrier.
Carrier block policies that retain messaging temporarily after a port.
Intentional hosting of messaging with another carrier.

Telnyx provides visibility into messaging port status and automatically escalates issues when messaging fails to activate at the FOC date and time.

Constraints

Messaging porting tracking is only applicable to US and Canada local and toll-free phone numbers.
The messaging_capable attribute must be true on the porting order to enable messaging tracking.
A messaging_profile_id must be assigned to the porting order when enabling messaging activation.
Phone numbers ported from other countries have messaging port simultaneously with voice.

Messaging port statuses

The messaging_port_status field tracks messaging activation independently from the porting order’s main status field. A porting order can have a status of ported (voice has ported) while the messaging_port_status is still activating or exception.

Status	Description
`pending`	Messaging activation is enabled but the porting order has not yet reached the FOC date and time.
`activating`	The porting order has ported and Telnyx is verifying messaging activation.
`ported`	Messaging has successfully ported to Telnyx.
`exception`	Messaging failed to port automatically and Telnyx is escalating with the losing carrier.
`not_applicable`	Messaging activation was not enabled for this porting order.

How it works

Step 1: Verify messaging capability

Check the messaging_capable attribute on your porting order or portability check response. Use the POST /v2/portability_checks endpoint to verify capability before creating a porting order, or check the messaging object on an existing porting order using the GET /v2/porting_orders/{id} endpoint.

If messaging_capable is true, Telnyx can support messaging for the phone numbers on the order.
If messaging_capable is false, Telnyx cannot support messaging for those phone numbers.

Step 2: Enable messaging activation

To enable messaging tracking and activation, update the porting order using the PATCH /v2/porting_orders/{id} endpoint. Set enable_messaging to true in the messaging object. You must also assign a messaging_profile_id in the phone_number_configuration object. This messaging profile is applied to all phone numbers on the order upon porting. The porting order must be in draft, in-process, or exception status to enable this feature.

Step 3: Monitor messaging port status

Prior to the FOC date and time, the order reflects messaging_port_status: pending. Once the porting order transitions to ported status, the messaging port status changes to activating while Telnyx verifies messaging activation. In most cases, the losing carrier releases the NNID at the FOC date and time, and the status updates to ported.

Step 4: Handle exceptions

If the losing carrier fails to release messaging, the status changes to exception. When this occurs, the Telnyx Messaging Ops team is automatically notified and escalates with the losing carrier. Resolution typically occurs within 72 hours for local numbers and up to 5 business days for toll-free numbers. Once resolved, the messaging_port_status updates to ported.

Webhook notifications

Follow this support article to set up webhook notifications for messaging port status changes. Select the Notification Setting “Port In Notifications” to receive porting_order.messaging_changed events.

Partial messaging ports

When a porting order contains multiple phone numbers, it is possible for some numbers to port messaging successfully while others do not. If any phone number on the order fails to port messaging, the order-level messaging_port_status is exception. To check the messaging port status of individual phone numbers, use the GET /v2/porting_orders/{id}/associated_phone_numbers endpoint. Each phone number has its own messaging_port_status attribute indicating whether that specific number ported messaging successfully.

Hosted SMS alternative

To avoid potential messaging downtime during porting, you can port SMS to Telnyx before porting voice by submitting a Hosted SMS request. This approach ensures messaging is active on Telnyx before the FOC date and time. The hosted SMS workflow involves:

Submitting a Hosted SMS request for your phone numbers at least 4 business days before the scheduled FOC date.
Creating a porting order with a FOC date at least 4 business days in the future.
Once the Hosted SMS request completes, SMS routes through Telnyx while voice remains with the losing carrier.
When the FOC date arrives, voice ports and both services route through Telnyx with no downtime.

For more information, see the Hosted SMS messaging process support article.

Troubleshooting

Porting voice only without messaging

To port only voice to Telnyx while hosting messaging elsewhere, do not enable messaging activation on the porting order. Leave enable_messaging as null and do not assign a messaging_profile_id. The messaging_port_status remains not_applicable and Telnyx does not attempt to override the NNID. If you later decide to activate messaging with Telnyx, see the Send a message guide.

Porting non-US and non-Canada phone numbers

For phone numbers outside of the US and Canada, voice and messaging port simultaneously when the order transitions to ported status. Messaging porting tracking is available but not required for these numbers. You can optionally enable messaging activation to receive status updates and webhook notifications.

Messaging port status shows exception

An exception status indicates one or more phone numbers on the order are still routing SMS through the losing carrier. Telnyx is automatically escalating with the losing carrier. Continue routing messaging through the losing carrier until you receive notification that messaging has ported.

Expected messaging port timing

For US and Canada local phone numbers, approximately 90% of orders have messaging activated within 10 minutes of porting. The remaining orders typically complete within 1-2 business days. For US and Canada toll-free phone numbers, messaging usually ports within 10 minutes. If activation does not occur within that window, resolution may take 4-5 business days. For all other phone numbers, messaging ports simultaneously with voice.

Messaging shows ported but messages fail to deliver

Verify that the phone number has a valid messaging_profile_id assigned. If a messaging profile is assigned and messages still fail, contact support for investigation.

Unable to enable messaging activation

Verify that the porting order shows messaging_capable: true and the order status is draft, in-process, or exception. If these conditions are met and you cannot enable messaging activation, contact support for assistance.

Bundles with porting

Source: https://developers.telnyx.com/docs/numbers/porting/bundles-porting.md

Overview

Bundle pre-configuration allows you to associate bundles with phone numbers on a porting order before those numbers are active at Telnyx. When the port completes and the phone numbers become active, the pre-configured bundles are automatically applied. The term “pre-configure” is used because bundles are not actually applied to phone numbers until after the numbers port in and become active at Telnyx. During the porting process, the bundle association exists as a pending configuration that takes effect upon port completion.

Constraints

Bundle pre-configuration is only available via API.
Bundles can be pre-configured or updated at any point before the porting order reaches ported or cancelled status, including shortly before the FOC date.
Each bundle can only be associated with one phone number. If a pre-configured bundle is used elsewhere before the port completes, the assignment will fail.
You can pre-configure up to 20 phone numbers per API request.
The bundle must be valid for the specific phone number type and characteristics. Invalid bundle-number combinations will return an error.
Pre-configuring bundles is optional. You can pre-configure bundles for some, all, or none of the phone numbers on a porting order.

How it works

Step 1: Verify available bundles

Use the GET /v2/bundle-pricing/user_bundles endpoint to list your bundles, or view them on the Bundles page in Mission Control Portal. A bundle is available for pre-configuration if its resources array is empty. Each bundle has eligibility criteria for which phone numbers it can be assigned to. To purchase additional bundles, visit the Bundle Orders page.

Step 2: Get porting phone number IDs

Each phone number on a porting order has a unique porting_phone_number_id that you need for pre-configuration. Use the GET /v2/porting_phone_numbers endpoint with a filter for your porting order ID to retrieve the list of phone numbers and their associated IDs.

Step 3: Pre-configure bundles

Use the POST /v2/porting_orders/phone_number_configurations endpoint to associate bundles with porting phone numbers. Each configuration requires:

porting_phone_number_id: The ID of the phone number on your porting order.
user_bundle_id: The ID of the bundle to pre-configure.

Step 4: Verify configurations

Use the GET /v2/porting_orders/phone_number_configurations endpoint with your porting order ID to view which bundles are pre-configured with which phone numbers. When the port completes and phone numbers become active at Telnyx, the pre-configured bundles are automatically applied to the corresponding phone numbers.

Port-in blocks

Source: https://developers.telnyx.com/docs/numbers/porting/port-in-blocks.md

Overview

Block porting allows you to port consecutive groups of phone numbers (blocks) from another carrier to Telnyx. Unlike porting individual phone numbers, block porting handles entire ranges of numbers that are assigned together by carriers. Phone number blocks are groups of consecutive phone numbers—typically 10, 100, or 1,000 numbers in sequence—assigned to a specific area or provider. Carriers manage these blocks as units, which means porting rules differ from individual numbers. Some countries require the entire block to be ported even if only some numbers are active. By indicating that you are porting a block (rather than individual numbers), Telnyx can apply the correct processing rules and help you avoid rejections or exceptions during the porting process.

Constraints

Block porting is currently only available for Germany (DE) port orders.
The maximum size for a single block is 1,000 phone numbers (0 - 999).
Activation ranges must be equal to or a subset of the phone number range.
Activation ranges cannot overlap with each other.
When adding a block to an existing order, the block must match the order’s country and phone number type.
Blocks can only be added or deleted when the order is in draft, in-process, or exception status.

Phone number range and activation ranges

When porting a block, you specify two key components: Phone number range: The complete block of consecutive numbers being ported. This defines the full range that will transfer to Telnyx and must be included in the Letter of Authorization (LOA). Block sizes are typically 10, 100, or 1,000 numbers. Activation ranges: The subset of numbers within the block that you want active immediately upon port completion. Numbers in the phone number range but not in any activation range will still port to your account but remain inactive. This separation is useful when a country requires full-block porting but you only need certain numbers active. For example, if you own a 1,000-number block but only use 776 of them, you can port the entire block while activating only the numbers you need. You can specify multiple activation ranges within a single block. For instance, if you need numbers 000-064 and number 087 active, you would define two separate activation ranges.

How it works

Step 1: Create a port order with blocks

Use the POST /v2/porting_orders endpoint to create an order. Include a phone_number_blocks array with:

phone_number_range: The start_at and end_at values defining the complete block.
activation_ranges: An array specifying which numbers to activate upon completion.

Both range values must be in E.164 format.

Step 2: Add blocks to an existing order (if needed)

If you created an order for individual numbers that were rejected because they belong to a block, you can add the block to your existing order rather than starting over. Use the POST /v2/porting_orders/{porting_order_id}/phone_number_blocks endpoint to add a block. Any phone numbers already on the order that fall within the block range will be incorporated automatically.

Step 3: View blocks on your order

Use the GET /v2/porting_orders/{porting_order_id}/phone_number_blocks endpoint to view all blocks associated with your order. Each block has a unique id. When you query porting phone numbers using the List porting phone numbers endpoint, numbers that belong to a block include a block_reference_id field linking them to their block.

Step 4: Remove a block (if needed)

Use the DELETE /v2/porting_orders/{porting_order_id}/phone_number_blocks/{id} endpoint to remove a block from an order. When you delete a block, the individual phone numbers remain on the order—only the block grouping is removed.

Port-out orders

Source: https://developers.telnyx.com/docs/numbers/porting/port-out-quickstart.md

Overview

A port-out order is created when another carrier requests to transfer phone numbers away from your Telnyx account. This occurs when an end-user authorizes a new carrier to port their number, and that carrier submits a port-in request to Telnyx. When Telnyx receives a port-out request, the system automatically creates a port-out order in your account. You can then review the order details and choose to authorize or reject the request based on the information provided. Port-out orders require a response within 24–48 hours. If you do not respond within this window, the port-out is automatically authorized and will proceed on the requested FOC (Firm Order Commitment) date.

Port-out order statuses

Each port-out order has a status field that indicates its current state in the porting process:

Status	Description
`pending`	The port-out request has been received and is awaiting your review.
`authorized`	You have approved the port-out request. The numbers will port on the FOC date.
`rejected-pending`	You have submitted a rejection. The Porting Ops team is reviewing the rejection reason to ensure it is valid.
`rejected`	The port-out request has been formally rejected and will not proceed.
`canceled`	The port-out request has been canceled by the gaining carrier or Telnyx.
`ported`	The phone numbers have successfully ported to the gaining carrier.

How it works

Step 1: Review incoming port-out orders

Use the GET /v2/portouts endpoint to list all port-out orders on your account, or use the GET /v2/portouts/:id endpoint to retrieve a specific order by ID. Review the order details including phone_numbers, carrier_name, requested_foc_date, and any subscriber information to verify the request is valid.

Step 2: Authorize or reject the order

After reviewing the port-out order, you must either authorize or reject it. To authorize a port-out: Use the PATCH /v2/portouts/:id/authorized endpoint where :id is the port-out order ID. Once authorized, the phone numbers are cleared to port out on the FOC date. To reject a port-out: First, retrieve the available rejection codes for your specific order using the GET /v2/portouts/rejections/:portout_id endpoint. The available rejection codes vary depending on the phone numbers in the order. Then, use the PATCH /v2/portouts/:id/rejected-pending endpoint with the appropriate rejection_code in the request body. If you use rejection code 1001 (“Other”), you must include a reason field explaining why you are rejecting the order. The Porting Ops team reviews the rejection reason to ensure it is valid. If the reason is not valid, the order is moved back to pending and you are notified to review it again.

Notifications

To receive updates when port-out order statuses change or new comments are added, configure port-out notifications in your account. Notifications can be sent via email or webhook. For setup instructions and webhook payload examples, see the Port-out order notifications guide. To view and republish port-out events programmatically, see the Port-out events API guide.

Port out order notifications

Source: https://developers.telnyx.com/docs/numbers/porting/port-out-notifications.md

We understand the importance of being able to track the progress and status of your port orders. That is why we offer port-out notifications for the following events:

Port-out order status changes
New comments

Notifications can be emitted to either email or webhook addresses. The following sections will discuss how to enable notification settings on your account, as well as provide example responses to the various webhook notification events.

How to set up port-out notifications

If you are adding port-out notification settings in the portal, they will apply for all port orders that you create. Here is how to get started:

Sign in to the Telnyx Portal
Go to your Account Settings and click on the Advanced Features section. Then select Notifications.
Click on the New Profile button to create a new Notification Profile
Click on the New Channel button to specify which email or webhook URL to send notifications to. Add as many notification channels as you would like!
Click on the New Setting button, select Port Out Notifications and select the profile and channel that you would like Telnyx to send port-out notifications to.

If you have further questions, check out this support article or contact our customer support team.

Example webhook notification events

Transition to `pending` status

{
  "data": {
    "event_type": "portout.status_changed",
    "id": "3b19372e-38d4-4a9e-855f-a5a9ed5db4c2",
    "occurred_at": "2022-04-11T14:46:27Z",
    "payload": {
      "carrier_name": "Onvoy",
      "id": "477bf6c3-c6b9-478a-a035-33bd785d6ae7",
      "phone_numbers": [
        "{{phone_number}}"
      ],
      "spid": "073H",
      "status": "pending",
      "subscriber_name": null,
      "user_id": "40d68ba2-0847-4df2-be9c-b0e0cb673e75"
    },
    "record_type": "event"
  },
  "meta": {
    "attempt": 1,
    "delivered_to": "https://example.com/porting_webhooks"
  }
}

Transition to `rejected-pending` status

{
  "data": {
    "event_type": "portout.status_changed",
    "id": "70d3c550-f4bd-4fa4-8502-d40d265355c4",
    "occurred_at": "2022-04-11T14:47:37Z",
    "payload": {
      "carrier_name": "Telnyx",
      "id": "477bf6c3-c6b9-478a-a035-33bd785d6ae7",
      "phone_numbers": [
        "{{phone_number}}"
      ],
      "rejection_reason": "Reason for rejection",
      "spid": "073H",
      "status": "rejected-pending",
      "subscriber_name": null,
      "user_id": "40d68ba2-0847-4df2-be9c-b0e0cb673e75"
    },
    "record_type": "event"
  },
  "meta": {
    "attempt": 1,
    "delivered_to": "https://example.com/porting_webhooks"
  }
}

Transition to `rejected` status

{
  "data": {
    "event_type": "portout.status_changed",
    "id": "92db90da-409d-42bb-88a2-13741ac5f2cc",
    "occurred_at": "2022-04-11T14:48:02Z",
    "payload": {
      "carrier_name": "Telnyx",
      "id": "477bf6c3-c6b9-478a-a035-33bd785d6ae7",
      "phone_numbers": [
        "{{phone_number}}"
      ],
      "rejection_reason": "Reason for rejection",
      "spid": "073H",
      "status": "rejected",
      "subscriber_name": null,
      "user_id": "40d68ba2-0847-4df2-be9c-b0e0cb673e75"
    },
    "record_type": "event"
  },
  "meta": {
    "attempt": 1,
    "delivered_to": "https://example.com/porting_webhooks"
  }
}

Transition to `canceled` status

{
  "data": {
    "event_type": "portout.status_changed",
    "id": "480fd3a5-c580-48c4-b724-84a3170fc043",
    "occurred_at": "2022-04-11T14:50:39Z",
    "payload": {
      "carrier_name": "Telnyx",
      "id": "d17ac097-fc58-41f4-aab3-6dcd16cafae9",
      "phone_numbers": [
        "{{phone_number}}"
      ],
      "spid": "073H",
      "status": "canceled",
      "subscriber_name": null,
      "user_id": "40d68ba2-0847-4df2-be9c-b0e0cb673e75"
    },
    "record_type": "event"
  },
  "meta": {
    "attempt": 1,
    "delivered_to": "https://example.com/porting_webhooks"
  }
}

Transition to `authorized` status

{
  "data": {
    "event_type": "portout.status_changed",
    "id": "c147c471-e051-4cda-a547-c2f7e12b3445",
    "occurred_at": "2022-04-11T14:51:53Z",
    "payload": {
      "carrier_name": "Telnyx",
      "id": "b31bf5a7-cebb-4ae1-a34f-e3f6af550413",
      "phone_numbers": [
        "{{phone_number}}"
      ],
      "spid": "073H",
      "status": "authorized",
      "subscriber_name": null,
      "user_id": "40d68ba2-0847-4df2-be9c-b0e0cb673e75"
    },
    "record_type": "event"
  },
  "meta": {
    "attempt": 1,
    "delivered_to": "https://example.com/porting_webhooks"
  }
}

Transition to `ported` status

{
  "data": {
    "event_type": "portout.status_changed",
    "id": "8ed7a709-3659-41fe-8c49-7af0037ebf2d",
    "occurred_at": "2022-04-11T14:53:39Z",
    "payload": {
      "carrier_name": "Telnyx",
      "id": "b31bf5a7-cebb-4ae1-a34f-e3f6af550413",
      "phone_numbers": [
        "{{phone_number}}"
      ],
      "spid": "073H",
      "status": "ported",
      "subscriber_name": null,
      "user_id": "40d68ba2-0847-4df2-be9c-b0e0cb673e75"
    },
    "record_type": "event"
  },
  "meta": {
    "attempt": 1,
    "delivered_to": "https://example.com/porting_webhooks"
  }
}

New Comment

{
  "data": {
    "event_type": "portout.new_comment",
    "id": "0a9af296-a217-498c-a1ac-651a9fb0b2f5",
    "occurred_at": "2022-12-16T19:06:34Z",
    "payload": {
      "comment": "test comment",
      "id": "10ecb41e-c7b6-49a7-bf4a-23d8688b3ed6",
      "portout_id": "330f47af-4296-417a-84f6-05cec6ea5a8d",
      "user_id": "40d68ba2-0847-4df2-be9c-b0e0cb673e75"
    },
    "record_type": "event"
  },
  "meta": {
    "attempt": 1,
    "delivered_to": "https://webhook.site/98e5e9e2-4921-4a64-b3c8-da0c6ce760f3"
  }
}

FOC Date change

If the gaining carrier requests a FOC date change, we will emit the following notification. For port-out orders, the gaining carrier is allotted a grace period of 10 days, which means the gaining carrier can port the phone number at any point between the FOC date listed and the following 10 days. While most port out orders are expected to occur on the listed FOC date, there is no guarantee that they will be completed on that day.

{
  "data": {
    "event_type": "portout.foc_date_changed",
    "id": "0a9af296-a217-498c-a1ac-651a9fb0b2f5",
    "occurred_at": "2022-12-16T19:06:34Z",
    "payload": {
      "foc_date": "2022-12-20T00:00:00Z",
      "id": "330f47af-4296-417a-84f6-05cec6ea5a8d",
      "user_id": "40d68ba2-0847-4df2-be9c-b0e0cb673e75"
    },
    "record_type": "event"
  },
  "meta": {
    "attempt": 1,
    "delivered_to": "https://webhook.site/98e5e9e2-4921-4a64-b3c8-da0c6ce760f3"
  }
}

Port-out events

Source: https://developers.telnyx.com/docs/numbers/porting/port-out-events.md

Overview

Port-out events provide a detailed record of everything that happens during the port-out process. Each time a status changes, a comment is added, or a FOC date is updated, the system creates an event that you can query and track. This differs from port-out notifications, which push updates to your webhook or email as they occur. The Events API gives you on-demand access to view your complete event history and republish notifications for specific events if needed. With the Port-out Events API, you can:

View all events across your port-out orders.
Filter events by port-out order, event type, or date range.
Republish notifications for specific events to your configured webhook or email.

Event types

The following event types are generated during the port-out lifecycle:

Event type	Description
`portout.status_changed`	The port-out order transitioned to a new status.
`portout.new_comment`	A new comment was added to the port-out order.
`portout.foc_date_changed`	The FOC (Firm Order Commitment) date for the port-out was updated.

How it works

Step 1: List port-out events

Use the GET /v2/portout/events endpoint to retrieve a list of events for your port-out orders. You can filter results by portout_id to view events for a specific order, or retrieve all events across your account with pagination support.

Step 2: Republish event notifications

If you need to resend notifications for a specific event, use the POST /v2/portout/events/{id}/republish endpoint where {id} is the event ID. This endpoint republishes notifications only to channels you are currently subscribed to. To configure your notification settings, see how to set up port-out notifications. Republishing an event resends the notifications but does not create a new event in the system. Email notifications may take a few minutes to be delivered.

Regulatory & Documents

Regulatory Requirements

Source: https://developers.telnyx.com/docs/numbers/phone-numbers/regulatory-requirements.md

Prior to number activation, some phone numbers need additional information to satisfy regulatory requirements. These requirements are defined per:

Country
Phone number type
Action (ordering a phone number, or porting a phone number)

For example, porting a GB local phone number may have one set of requirements, while ordering a GB local phone number may have another set of requirements. Use the GET /requirements endpoint and accompanying filters to see what regulatory requirements need to be met to purchase/port a phone number. The API response will have two different record_type:

”record_type”: “requirement”: This is the parent record. It indicates which country, phone number type, and action combination that the regulatory requirements apply to. For example, DE local ordering.
”record_type”: “requirement_type”: Communicates the actual regulatory requirements that need to be fulfilled to unblock number activation in that particular country + phone number type + action combination. For example, a Proof of address.

Note: The regulatory landscape is constantly evolving. The regulatory requirements for phone numbers may change.

Fulfilling a `requirement_type`

To complete your order, all regulatory requirements requirement_type) must be fulfilled and approved. You can satisfy these requirements individually for each order, or you can use a requirement group to apply all the values at once. To view additional information on a regulatory requirement (description, examples, etc.), perform a GET /requirement_types/ request. If a requirement_type includes acceptance criteria, ensure the value provided meets those criteria. Each requirement_type has a type classification. There are four possible types:

textual
address
document
action

Each type has different rules for fulfillment.

Textual type

To fulfill a textual type, any string can be provided (assuming it complies with the acceptance_criteria of the requirement_type)

Address type

To fulfill an address requirement, an address id must be provided as the field value. Create an address using the POST v2/addresses endpoint. Upon successful creation, the address will have a unique id associated with it (for example 1293384261075731499). Pass that id as the field_value for the address ordering requirement. You cannot write out the address as a string (i.e. “312 W Superior St, Chicago, IL, 60654, US”). You must create the address with the POST v2/addresses endpoint, and pass the address id as the field_value.

Document type

To fulfill a document requirement, a document id must be provided as the field value. Upload the document using the POST /documents endpoint. Upon successful upload, an id will be returned in the response that corresponds to the document (for example 6a09cdc3-8948-47f0-aa62-74ac943d6c58). Pass that id as the field_value for the document ordering requirement.

Action type

An action requirement is unique, and very rare. Please see our separate developer guide to learn more about how to handle action requirement types.

Requirement groups

Source: https://developers.telnyx.com/docs/numbers/phone-numbers/requirement-groups.md

Overview

Requirement groups allow you to view, manage, and fulfill regulatory requirements in advance for a particular order type. By creating a requirement group, you can pre-fill all necessary information and documentation just once, and then reuse this group across multiple orders. Each requirement group is specific to a combination of country_code, phone_number_type, and action (ordering or porting). Once created and fulfilled, the group can be associated with any number order or porting order that matches those criteria. The pre-filled requirements are automatically applied to the order, which then undergoes the standard regulatory review process.

Constraints

Requirement groups are optional in most countries. You can fulfill requirements individually on each order or use requirement groups to pre-fill requirements.
In the following countries, it is mandatory to use fulfilled requirement groups when placing a number order: CH (Switzerland), DK (Denmark), IT (Italy), NO (Norway), PT (Portugal), and SE (Sweden).
A fulfilled requirement group means that every requirement in the group has an associated value. You cannot create an order with an empty requirement group in countries where requirement groups are mandatory.
Requirement groups can only be associated with orders that match the group’s country_code, phone_number_type, and action combination. For example, a DE local ordering requirement group can only be applied to DE local number orders.
Number orders do not automatically synchronize with requirement group changes. You must make another API request to apply updated requirement group values to existing orders.

Requirement group statuses

Each requirement group has a status that indicates its current state and what review process orders using it will undergo. All requirement groups except no-longer-eligible can be used for orders.

Status	Description
unapproved	Default status after creation. Has not been submitted for pre-approval. Orders using this group go through standard review.
pending-approval	Submitted and under review. Orders using this group go through standard review.
approved	Passed review. Orders using this group activate automatically within a few minutes.
declined	One or more requirements were rejected during pre-approval. Orders using this group go through standard review. Expect similar rejections on orders using this group.
expired	Requirement(s) exceeded validity window. Orders using this group go through standard review. Expect similar rejections on orders using this group. Review `regulatory_requirements.expires_at` for expiration dates.
no-longer-eligible	Regulatory requirements have changed. Cannot be used for orders. Create a new requirement group with current requirements.

Pre-approval

By default, orders using requirement groups go through standard review, where Number Ops manually reviews the requirements on each individual order after it is placed. This review process can take time before numbers activate. Pre-approval is an optional feature that allows you to submit a requirement group for review before placing orders. Once a requirement group is pre-approved, orders using it can activate automatically within a few minutes, bypassing the standard review process. You do not need to pre-approve a requirement group to use it for ordering. Any requirement group (except no-longer-eligible) can be associated with orders immediately after creation and fulfillment. When to use pre-approval: Pre-approval makes sense when you will reuse the same requirement group for multiple orders AND you need quick number activation. Orders using approved requirement groups will activate automatically within a few minutes, bypassing the standard review process. When to skip pre-approval: If you’re only using a requirement group for a few orders or don’t need immediate activation, you can skip pre-approval entirely. Orders using unapproved, pending-approval, declined, or expired requirement groups will go through the standard review process. Pre-approval limitations:

Country coverage: Requirement group pre-approval is supported in most countries, but not all. Some countries, such as Italy, do not support pre-approval. If you attempt to submit a requirement group for pre-approval in a country where it is not supported, you will receive an error.
Address validation: If the requirement group has an address requirement, ensure that ordered phone numbers comply with that address requirement. For example, if the requirement specifies an address matching the DID area code and the approved address is in Munich, order a phone number in Munich. Ordering a number in a different area (e.g., Berlin) will cause the order to undergo standard review instead of immediate activation. If the requirement specifies a national address, the address must be within the same country as the ordered phone number.

How it works

Step 1: Create a requirement group

Use the POST /v2/requirement_groups endpoint to create a requirement group. Each group requires country_code (ISO Alpha-2 format), phone_number_type (local, toll_free, national, mobile, or shared_cost), and action (ordering or porting). Optionally include a customer_reference to label the requirement group for your own tracking purposes.

Step 2: View the requirement group

List all requirement groups using GET /v2/requirement_groups, or retrieve a specific group by ID using GET /v2/requirement_groups/:id. The regulatory_requirements array lists each requirement that needs to be fulfilled for your order. Each requirement has a unique requirement_id. For detailed information about requirement types, see the regulatory requirements guide.

Step 3: Fulfill the requirement group

Update the requirement group with values using PATCH /v2/requirement_groups/:id. In the request body, specify each requirement_id and its associated value. For more information, check out the regulatory requirements guide.

Step 4: Associate the requirement group with an order

You can associate a requirement group with number orders or porting orders. For new number orders: First, search for available phone numbers and identify the number(s) you would like to purchase. Then create a number order using POST /v2/number_orders, including the requirement_group_id in each phone_number object. The requirement group values will populate the order and undergo regulatory review. For existing pending sub number orders: Update a pending sub number order using POST /v2/sub_number_orders/:id/requirement_group. Include the requirement_group_id in the request body. When updating an existing order, the requirement group must be fulfilled. The request will only update non-approved requirements. If a requirement is already approved, its value remains unchanged. For porting orders: Associate a requirement group with a porting order using PATCH /v2/porting_orders/:id, including the requirement_group_id in the request body. This request can be performed when the order is in draft, in-process, or exception status. Any existing requirement values will be overwritten by the requirement group.

Step 5 (Optional): Submit for pre-approval

To submit a requirement group for pre-approval, use the POST /v2/requirement_groups/:id/submit_for_approval endpoint. The requirement group will transition to pending-approval status after submission. Telnyx will review the submitted group. If all requirements are met, the group’s status is set to approved. If requirements are rejected, the status will move to declined. If the requirement group is rejected, Number Ops will communicate feedback via comments on the requirement group. You can view and respond to these comments using the comments API:

POST /v2/comments to create a comment.
GET /v2/comments to retrieve all comments.

When using the comments API for requirement groups, set comment_record_type to requirement_group and comment_record_id to the requirement_group_id. Once a requirement group is approved, associate the requirement_group_id with orders following the process described in Step 4.

Webhook notifications

You can configure webhook notifications to receive updates about requirement group status changes. Follow this support article to set up webhook notifications. Select the “Requirement Group Status Change” notification setting to receive webhooks when a requirement group transitions between statuses (e.g., from pending-approval to approved or declined).

Action requirements

Source: https://developers.telnyx.com/docs/numbers/phone-numbers/action-ordering-requirement.md

Overview

Action requirements are a special type of regulatory requirement for international phone number orders that cannot be fulfilled by submitting documents or text information. Instead, these requirements need the end user to complete an external action, such as identity verification through a third-party service. Each action requirement type may have different fulfillment steps depending on the specific verification needed. This guide provides detailed instructions for completing each action requirement. As new action requirement types are introduced, this guide will be updated with their specific fulfillment processes.

Australia mobile ID verification

Australia mobile number orders require end user identity verification to comply with local telecommunications regulations. To facilitate a secure and efficient verification experience, Telnyx has partnered with Onfido, a trusted identity verification provider.

Requirement ID

The Australia mobile ID verification requirement has the following identifier:

Requirement ID: b7c72fb8-fa08-4529-aaf6-b9117d3f3698

This ID is used when initiating the verification process through the external requirements endpoint.

Verification process

To complete ID verification for an Australia mobile number order:

Generate a unique verification link by making a request to the POST /v2/external_requirements/{requirement_id}/sub_number_orders/{sub_order_id} endpoint. Include the end user’s first_name and last_name in the request body.
The API returns a URL in the requirement_action.value field. Share this URL with the end user to access Onfido’s secure ID verification portal.
The end user visits the provided URL and completes the identity verification process by submitting required identification documents through the Onfido portal.
Once submitted, the verification is reviewed. Upon approval, the requirement is automatically marked as completed on the number order.
The order’s requirements_met field updates to true, allowing the order to proceed to the next stage.

Documents

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

Overview

The Documents API allows you to upload and manage files that are required for regulatory compliance, identity verification, and other services on your Telnyx account. Documents are commonly used when ordering phone numbers in countries that require proof of identity, proof of address, or other supporting documentation. Once uploaded, documents must be linked to a service (such as a number order or regulatory requirement) within 30 minutes, or they will be automatically deleted. This ensures that only actively used documents are retained on your account. You can upload documents by sending base64-encoded file content or by uploading the file directly via multipart form data.

Constraints

Maximum file size is 20 MB.
Maximum filename length is 512 characters.
Filenames must contain only printable Unicode characters. Non-printable characters (control characters) are not allowed.
Spaces in filenames are automatically removed. For example, my document.pdf becomes mydocument.pdf.
The file extension is automatically appended based on the detected MIME type, even if omitted from the filename.
Uploaded documents must be linked to a service within 30 minutes or they will be automatically deleted.
Documents that are linked to a service cannot be deleted until they are unlinked.
All uploaded documents are scanned for malware. Documents flagged as infected will be denied.

Accepted file types

The following file types are accepted for upload:

File type	MIME type
PDF	`application/pdf`
PNG	`image/png`
JPEG	`image/jpeg`
CSV	`text/csv`, `application/csv`
Plain text	`text/plain`
JSON	`application/json`
Word (.docx)	`application/vnd.openxmlformats-officedocument.wordprocessingml.document`
Word (.doc)	`application/msword`
Excel (.xlsx)	`application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`
Excel (.xls)	`application/vnd.ms-excel`

Upload methods

Documents can be uploaded using any of three methods through the POST /documents endpoint:

Base64: Provide the file content as a base64-encoded string in the file field, along with a filename.
Multipart form data: Upload the file directly as binary data using multipart/form-data.

You can optionally include a customer_reference with any upload method to associate your own tracking identifier with the document.

Antivirus scan statuses

All uploaded documents are scanned for malware. The av_scan_status field indicates the scan result:

Status	Description
`pending_scan`	The document is queued for scanning.
`scanned`	The scan completed and no threats were detected.
`infected`	The scan detected malware. The document will be denied.
`not_scanned`	The document has not yet been scanned.

Document links

When a document is attached to a service on your account (such as a number order or regulatory requirement), a document link is automatically created. You do not need to create these links manually — they are managed by the services that use the document. You can use the GET /document_links endpoint to view which services a document is currently associated with. You can filter results by document_id, linked_record_type, or linked_resource_id.

Identity

Number lookup using Telnyx APIs

Source: https://developers.telnyx.com/docs/identity/number-lookup/quickstart.md

Lookup: Carrier and caller name

cURL

Number Lookup is a service offered by the Telnyx SDK that allows the user to look up a phone number and retrieve information regarding that phone number such as:

Carrier name
Type of phone (landline, mobile, etc.)
Name and business associated with the number

Basic number lookup example

Running the following code will perform a number lookup on the given number parameter. Don’t forget to update YOUR_API_KEY here.

curl -X GET \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --globoff "https://api.telnyx.com/v2/number_lookup/+18665552368"

After pasting the above content, Kindly check and remove any new line added The response will look something like this:

{
  "data": {
    "caller_name": {
      "caller_name": "TELNYX LLC",
      "error_code": "10001"
    },
    "carrier": {
      "error_code": null,
      "mobile_country_code": "US",
      "mobile_network_code": 866,
      "name": "Telnyx/4",
      "type": "voip"
    },
    "country_code": "US",
    "fraud": null,
    "national_format": "(0312) 945-7420",
    "phone_number": "+13129457420",
    "portability": {
      "altspid": "073H",
      "altspid_carrier_name": "Telnyx/4",
      "altspid_carrier_type": "3",
      "city": "WAUKEGAN",
      "line_type": "voip",
      "lrn": "2245701999",
      "ocn": "073H",
      "ported_date": "2017-10-20",
      "ported_status": "Y",
      "spid": "073H",
      "spid_carrier_name": "Telnyx/4",
      "spid_carrier_type": "3",
      "state": "Illinois"
    },
    "record_type": "number_lookup"
  }
}

After pasting the above content, Kindly check and remove any new line added This example shows results for a Telnyx user-owned number. It displays the formatted version of the number in the national-format value. The location of the number can be seen under portability -> city and state. Other useful information such as carrier and caller_name can be retrieved if available.

Retrieving caller name and carrier

Users may also specify the type of the request in order to receive information about the carrier and caller-name. Note that the request will always return the same object, however if the caller-name and carrier options are not sent, the return values will be null. An example of adding both these parameters to the request is shown below:

curl -X GET \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --globoff "https://api.telnyx.com/v2/number_lookup/+18665552368?carrier&caller-name"

After pasting the above content, Kindly check and remove any new line added

Python

Number Lookup is a serviceis a service offered by the Telnyx SDK that allows the user to look up a phone number and retrieve information regarding that phone number such as:

Carrier name
Type of phone (landline, mobile, etc.)
Name and business associated with the number

Basic number lookup example

Running the following code will perform a number lookup on the given number parameter using Python.

import telnyx
telnyx.api_key = "YOUR_API_KEY"
telnyx.NumberLookup.retrieve(“+13129457420”)

After pasting the above content, Kindly check and remove any new line added The response will look something like this:

{
  "data": {
    "caller_name": {
      "caller_name": "TELNYX LLC",
      "error_code": "10001"
    },
    "carrier": {
      "error_code": null,
      "mobile_country_code": "US",
      "mobile_network_code": 866,
      "name": "Telnyx/4",
      "type": "voip"
    },
    "country_code": "US",
    "fraud": null,
    "national_format": "(0312) 945-7420",
    "phone_number": "+13129457420",
    "portability": {
      "altspid": "073H",
      "altspid_carrier_name": "Telnyx/4",
      "altspid_carrier_type": "3",
      "city": "WAUKEGAN",
      "line_type": "voip",
      "lrn": "2245701999",
      "ocn": "073H",
      "ported_date": "2017-10-20",
      "ported_status": "Y",
      "spid": "073H",
      "spid_carrier_name": "Telnyx/4",
      "spid_carrier_type": "3",
      "state": "Illinois"
    },
    "record_type": "number_lookup"
  }
}

Retrieving caller name and carrier

Node

Number Lookup is a serviceoffered by the Telnyx SDK that allows the user to look up a phone number and retrieve information regarding that phone number such as:

Carrier name
Type of phone (landline, mobile, etc.)
Name and business associated with the number

Basic number lookup example

Running the following code will perform a number lookup on the given number parameter.

import Telnyx from 'telnyx';

const telnyx = new Telnyx("YOUR_API_KEY");

// In Node 10
const { data: numberInfo } = await telnyx.numberLookup.retrieve(
  '+18665552368'
);

// In other environments
telnyx.numberLookup.retrieve(
  '+18665552368'
).then(function(response){
  const numberInfo = response.data; // asynchronously handled
});

After pasting the above content, Kindly check and remove any new line added The response will look something like this:

{
  "data": {
    "caller_name": {
      "caller_name": "TELNYX LLC",
      "error_code": "10001"
    },
    "carrier": {
      "error_code": null,
      "mobile_country_code": "US",
      "mobile_network_code": 866,
      "name": "Telnyx/4",
      "type": "voip"
    },
    "country_code": "US",
    "fraud": null,
    "national_format": "(0312) 945-7420",
    "phone_number": "+13129457420",
    "portability": {
      "altspid": "073H",
      "altspid_carrier_name": "Telnyx/4",
      "altspid_carrier_type": "3",
      "city": "WAUKEGAN",
      "line_type": "voip",
      "lrn": "2245701999",
      "ocn": "073H",
      "ported_date": "2017-10-20",
      "ported_status": "Y",
      "spid": "073H",
      "spid_carrier_name": "Telnyx/4",
      "spid_carrier_type": "3",
      "state": "Illinois"
    },
    "record_type": "number_lookup"
  }
}

Retrieving caller name and carrier

import Telnyx from 'telnyx';

const telnyx = new Telnyx("YOUR_API_KEY");

// In Node 10
const { data: numberInfo } = await telnyx.numberLookup.retrieve(
  '+18665552368',
  {
    type: ["caller-name", "carrier"]
  }
);

// In other environments
telnyx.numberLookup.retrieve(
  '+18665552368',
  {
    type: ["caller-name", "carrier"]
  }
).then(function(response){
  const numberInfo = response.data; // asynchronously handled
});

After pasting the above content, Kindly check and remove any new line added

Ruby

Number Lookup is a service is a service offered by the Telnyx SDK that allows the user to look up a phone number and retrieve information regarding that phone number such as:

Carrier name
Type of phone (landline, mobile, etc.)
Name and business associated with the number

Basic number lookup example

Running the following code will perform a number lookup on the given number parameter.

require "telnyx"
Telnyx.api_key = "YOUR_API_KEY"

Telnyx::NumberLookup.retrieve('+12624755500')

After pasting the above content, Kindly check and remove any new line added The response will look something like this:

{
  "data": {
    "caller_name": {
      "caller_name": "TELNYX LLC",
      "error_code": "10001"
    },
    "carrier": {
      "error_code": null,
      "mobile_country_code": "US",
      "mobile_network_code": 866,
      "name": "Telnyx/4",
      "type": "voip"
    },
    "country_code": "US",
    "fraud": null,
    "national_format": "(0312) 945-7420",
    "phone_number": "+13129457420",
    "portability": {
      "altspid": "073H",
      "altspid_carrier_name": "Telnyx/4",
      "altspid_carrier_type": "3",
      "city": "WAUKEGAN",
      "line_type": "voip",
      "lrn": "2245701999",
      "ocn": "073H",
      "ported_date": "2017-10-20",
      "ported_status": "Y",
      "spid": "073H",
      "spid_carrier_name": "Telnyx/4",
      "spid_carrier_type": "3",
      "state": "Illinois"
    },
    "record_type": "number_lookup"
  }
}

Retrieving caller name and carrier

Telnyx verify quickstart

Source: https://developers.telnyx.com/docs/identity/verify/quickstart.md

In this tutorial, you’ll learn how to deliver a 2FA token to any mobile number and verify that token using the Telnyx v2 API. Examples are provided in curl, Node.js, Python, Ruby, Go, Java, .NET, and PHP.

Prerequisites

Sign up at telnyx.com if you don’t have an account yet. Follow the API Keys guide to generate an API key. Set it as an environment variable:

macOS/Linux

export TELNYX_API_KEY="YOUR_API_KEY"

Windows

$env:TELNYX_API_KEY = "YOUR_API_KEY"

If you prefer using an SDK over curl, install one for your language:

Node.js

npm install telnyx

Python

pip install telnyx

Ruby

gem install telnyx

go get github.com/team-telnyx/telnyx-go

PHP

composer require telnyx/telnyx-php

For Java and .NET, the examples use the standard HTTP client libraries included with the platform.

Methods of verification

There are currently three verification methods available:

sms - the verification code is sent in a custom or default templated message.
call - the code is spoken aloud in a custom or default templated message when the user answers the call.
flashcall - the verification code is embedded in the caller ID of a brief “flash” call (the call rings once and hangs up). The user’s app extracts the code automatically.

Create a verify profile

A Verify Profile contains several important configurations that you’ll use when sending 2-factor authentication messages and receiving responses. Before you send any 2FA messages, you need a profile to go with them. Each profile can have one of each verification method configured. It is recommended that if you wish to configure multiple applications, you use a different profile for each one. In the below example we will set up a verification profile that can use SMS using a selected message template and speech to text calling.

Select a message template

curl

curl --location --request GET 'https://api.telnyx.com/v2/verify_profiles/templates' \
--header 'Authorization: Bearer YOUR_API_KEY'

Node

import Telnyx from 'telnyx';

const client = new Telnyx({
  apiKey: process.env['TELNYX_API_KEY'],
});

const templates = await client.verifyProfiles.retrieveTemplates();

for (const template of templates.data) {
  console.log(`${template.id}: ${template.text}`);
}

Python

import os
from telnyx import Telnyx

client = Telnyx(api_key=os.environ.get("TELNYX_API_KEY"))

templates = client.verify_profiles.retrieve_templates()

for template in templates.data:
    print(f"{template.id}: {template.text}")

Ruby

require "telnyx"
require "json"
require "net/http"
require "uri"

uri = URI("https://api.telnyx.com/v2/verify_profiles/templates")
req = Net::HTTP::Get.new(uri)
req["Authorization"] = "Bearer #{ENV['TELNYX_API_KEY']}"

res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
data = JSON.parse(res.body)

data["data"].each do |template|
  puts "#{template['id']}: #{template['text']}"
end

package main

import (
  "context"
  "fmt"
  "os"

  "github.com/team-telnyx/telnyx-go"
  "github.com/team-telnyx/telnyx-go/option"
)

func main() {
  client := telnyx.NewClient(option.WithAPIKey(os.Getenv("TELNYX_API_KEY")))

  templates, err := client.VerifyProfiles.RetrieveTemplates(context.TODO())
  if err != nil {
    panic(err)
  }
  for _, t := range templates.Data {
    fmt.Printf("%s: %s\n", t.ID, t.Text)
  }
}

Java

package com.telnyx.example;

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public final class ListTemplates {
    public static void main(String[] args) throws Exception {
        HttpClient httpClient = HttpClient.newHttpClient();

        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.telnyx.com/v2/verify_profiles/templates"))
            .header("Authorization", "Bearer " + System.getenv("TELNYX_API_KEY"))
            .GET()
            .build();

        HttpResponse response = httpClient.send(
            request, HttpResponse.BodyHandlers.ofString()
        );
        System.out.println(response.body());
    }
}

.NET

using System.Net.Http.Headers;

var httpClient = new HttpClient();
httpClient.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("TELNYX_API_KEY"));

var response = await httpClient.GetStringAsync(
    "https://api.telnyx.com/v2/verify_profiles/templates"
);
Console.WriteLine(response);

PHP

<?php
require_once 'vendor/autoload.php';

$apiKey = getenv('TELNYX_API_KEY');

$ch = curl_init('https://api.telnyx.com/v2/verify_profiles/templates');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer $apiKey",
    ],
]);
$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
foreach ($data['data'] as $template) {
    echo "{$template['id']}: {$template['text']}\n";
}

Example response

{
    "data": [
        {
            "id": "0abb5b4f-459f-445a-bfcd-488998b7572d",
            "text": "Your {{app_name}} verification code is: {{code}}."
        },
        {
            "id": "2ca3f1da-5621-4aa6-ae56-df21caff79e0",
            "text": "{{code}} is your verification code for {{app_name}}."
        },
        {
            "id": "33dfb056-6c1b-40bd-920e-4243e01248a5",
            "text": "Your {{app_name}} verification code is: {{code}}. Do not share this code with anyone; our employees will never ask for the code."
        },
        {
            "id": "46acd63c-be57-4993-ae8d-0e4067ad1d57",
            "text": "Your {{app_name}} verification code is: {{code}}. This code will expire in {{default_verification_timeout_secs}} minutes."
        },
        {
            "id": "723ead5e-ada6-4c29-a962-349170866187",
            "text": "{{code}} is your verification code for {{app_name}}. This code will expire in {{default_verification_timeout_secs}} minutes."
        },
        {
            "id": "88d0781f-f4c7-4b78-8d0a-1f3e4de78b5e",
            "text": "Your {{app_name}} verification code is: {{code}}. This code will expire in {{default_verification_timeout_secs}} minutes. Do not share this code with anyone; our employees will never ask for the code."
        }
    ]
}

If not selected then the default template is “Your verification code is {code}.” Want to use your own branded verification messages? You can now create custom templates that match your brand voice and compliance requirements.

Create a verify profile

curl

curl --location --request POST 'https://api.telnyx.com/v2/verify_profiles' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--data-raw '{
    "name": "foobar-en-v1",
    "language": "en-US",
    "sms": {
        "messaging_template_id": "0abb5b4f-459f-445a-bfcd-488998b7572d",
        "whitelisted_destinations": ["US", "CA"],
        "default_timeout_secs": 300,
        "code_length": 5
    },
    "call": {
        "default_timeout_secs": 600
    }
}'

Node

import Telnyx from 'telnyx';

const client = new Telnyx({
  apiKey: process.env['TELNYX_API_KEY'],
});

const profile = await client.verifyProfiles.create({
  name: 'foobar-en-v1',
  language: 'en-US',
  sms: {
    messaging_template_id: '0abb5b4f-459f-445a-bfcd-488998b7572d',
    whitelisted_destinations: ['US', 'CA'],
    default_timeout_secs: 300,
    code_length: 5,
  },
  call: {
    default_timeout_secs: 600,
  },
});

console.log('Profile ID:', profile.data.id);
console.log('Profile name:', profile.data.name);

Python

import os
from telnyx import Telnyx

client = Telnyx(api_key=os.environ.get("TELNYX_API_KEY"))

profile = client.verify_profiles.create(
    name="foobar-en-v1",
    language="en-US",
    sms={
        "messaging_template_id": "0abb5b4f-459f-445a-bfcd-488998b7572d",
        "whitelisted_destinations": ["US", "CA"],
        "default_timeout_secs": 300,
        "code_length": 5,
    },
    call={
        "default_timeout_secs": 600,
    },
)

print(f"Profile ID: {profile.data.id}")
print(f"Profile name: {profile.data.name}")

Ruby

require "telnyx"
require "json"
require "net/http"
require "uri"

uri = URI("https://api.telnyx.com/v2/verify_profiles")
req = Net::HTTP::Post.new(uri, "Content-Type" => "application/json")
req["Authorization"] = "Bearer #{ENV['TELNYX_API_KEY']}"
req.body = {
  name: "foobar-en-v1",
  language: "en-US",
  sms: {
    messaging_template_id: "0abb5b4f-459f-445a-bfcd-488998b7572d",
    whitelisted_destinations: ["US", "CA"],
    default_timeout_secs: 300,
    code_length: 5
  },
  call: {
    default_timeout_secs: 600
  }
}.to_json

res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
data = JSON.parse(res.body)

puts "Profile ID: #{data['data']['id']}"
puts "Profile name: #{data['data']['name']}"

package main

import (
  "context"
  "fmt"
  "os"

  "github.com/team-telnyx/telnyx-go"
  "github.com/team-telnyx/telnyx-go/option"
)

func main() {
  client := telnyx.NewClient(option.WithAPIKey(os.Getenv("TELNYX_API_KEY")))

  profile, err := client.VerifyProfiles.Create(context.TODO(), telnyx.VerifyProfileCreateParams{
    Name:     "foobar-en-v1",
    Language: telnyx.String("en-US"),
    SMS: &telnyx.VerifyProfileSMSParams{
      MessagingTemplateID:    telnyx.String("0abb5b4f-459f-445a-bfcd-488998b7572d"),
      WhitelistedDestinations: []string{"US", "CA"},
      DefaultTimeoutSecs:     telnyx.Int64(300),
      CodeLength:             telnyx.Int64(5),
    },
    Call: &telnyx.VerifyProfileCallParams{
      DefaultTimeoutSecs: telnyx.Int64(600),
    },
  })
  if err != nil {
    panic(err)
  }
  fmt.Printf("Profile ID: %s\n", profile.Data.ID)
  fmt.Printf("Profile name: %s\n", profile.Data.Name)
}

Java

package com.telnyx.example;

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public final class CreateVerifyProfile {
    public static void main(String[] args) throws Exception {
        String body = """
            {
                "name": "foobar-en-v1",
                "language": "en-US",
                "sms": {
                    "messaging_template_id": "0abb5b4f-459f-445a-bfcd-488998b7572d",
                    "whitelisted_destinations": ["US", "CA"],
                    "default_timeout_secs": 300,
                    "code_length": 5
                },
                "call": {
                    "default_timeout_secs": 600
                }
            }
            """;

        HttpClient httpClient = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.telnyx.com/v2/verify_profiles"))
            .header("Content-Type", "application/json")
            .header("Authorization", "Bearer " + System.getenv("TELNYX_API_KEY"))
            .POST(HttpRequest.BodyPublishers.ofString(body))
            .build();

        HttpResponse response = httpClient.send(
            request, HttpResponse.BodyHandlers.ofString()
        );
        System.out.println(response.body());
    }
}

.NET

using System.Net.Http.Headers;
using System.Text;
using System.Text.Json;

var httpClient = new HttpClient();
httpClient.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("TELNYX_API_KEY"));

var payload = new
{
    name = "foobar-en-v1",
    language = "en-US",
    sms = new
    {
        messaging_template_id = "0abb5b4f-459f-445a-bfcd-488998b7572d",
        whitelisted_destinations = new[] { "US", "CA" },
        default_timeout_secs = 300,
        code_length = 5
    },
    call = new { default_timeout_secs = 600 }
};

var content = new StringContent(
    JsonSerializer.Serialize(payload), Encoding.UTF8, "application/json"
);
var response = await httpClient.PostAsync(
    "https://api.telnyx.com/v2/verify_profiles", content
);
var body = await response.Content.ReadAsStringAsync();
Console.WriteLine(body);

PHP

<?php
require_once 'vendor/autoload.php';

$apiKey = getenv('TELNYX_API_KEY');

$payload = json_encode([
    'name' => 'foobar-en-v1',
    'language' => 'en-US',
    'sms' => [
        'messaging_template_id' => '0abb5b4f-459f-445a-bfcd-488998b7572d',
        'whitelisted_destinations' => ['US', 'CA'],
        'default_timeout_secs' => 300,
        'code_length' => 5,
    ],
    'call' => [
        'default_timeout_secs' => 600,
    ],
]);

$ch = curl_init('https://api.telnyx.com/v2/verify_profiles');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => $payload,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer $apiKey",
        'Content-Type: application/json',
    ],
]);
$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
echo "Profile ID: " . $data['data']['id'] . "\n";
echo "Profile name: " . $data['data']['name'] . "\n";

Example response

{
    "data": {
        "id": "4900017a-e7c8-e79e-0a7c-0d98f49b09cc",
        "name": "foobar-en-v1",
        "created_at": "2024-03-27T11:45:41.292913",
        "updated_at": "2024-03-27T11:45:41.292913",
        "record_type": "verify_profile",
        "sms": {
            "messaging_template_id": "0abb5b4f-459f-445a-bfcd-488998b7572d",
            "whitelisted_destinations": ["US", "CA"],
            "default_timeout_secs": 300,
            "code_length": 5
        },
        "call": {
            "default_timeout_secs": 600
        },
        "language": "en-US"
    }
}

Don’t forget to set your TELNYX_API_KEY environment variable or replace YOUR_API_KEY in the curl examples. Take note of the profile’s id that’s returned to you, you’ll need it to send 2FA verifications. At any time, you can access all of your created Verify Profiles by API as well. You are now ready to send 2-factor authentication messages!

Trigger a verification request

To send a verification attempt, you need the Verify Profile ID, the phone number that will receive the message, and the verification type. Choose the method that best fits your use case: SMS verification sends a code via text message. This is the most common method with the widest global coverage.

curl

curl -X POST \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --data '{"phone_number":"+13035551234","verify_profile_id":"4900017a-e7c8-e79e-0a7c-0d98f49b09cc"}' \
  https://api.telnyx.com/v2/verifications/sms

Node

import Telnyx from 'telnyx';

const client = new Telnyx({
  apiKey: process.env['TELNYX_API_KEY'],
});

const verification = await client.verifications.triggerSMS({
  phone_number: '+13035551234',
  verify_profile_id: '4900017a-e7c8-e79e-0a7c-0d98f49b09cc'
});

console.log('Verification ID:', verification.data.id);
console.log('Status:', verification.data.status); // "pending"

Python

import os
from telnyx import Telnyx

client = Telnyx(api_key=os.environ.get("TELNYX_API_KEY"))

verification = client.verifications.trigger_sms(
    phone_number="+13035551234",
    verify_profile_id="4900017a-e7c8-e79e-0a7c-0d98f49b09cc"
)

print(f"Verification ID: {verification.data.id}")
print(f"Status: {verification.data.status}")  # "pending"

Ruby

require "telnyx"

client = Telnyx::Client.new(api_key: ENV["TELNYX_API_KEY"])

verification = client.verifications.sms(
  phone_number: "+13035551234",
  verify_profile_id: "4900017a-e7c8-e79e-0a7c-0d98f49b09cc"
)

puts "Verification ID: #{verification.id}"
puts "Status: #{verification.status}" # "pending"

package main

import (
  "context"
  "fmt"
  "os"

  "github.com/team-telnyx/telnyx-go"
  "github.com/team-telnyx/telnyx-go/option"
)

func main() {
  client := telnyx.NewClient(option.WithAPIKey(os.Getenv("TELNYX_API_KEY")))

  verification, err := client.Verifications.SMS(context.TODO(), telnyx.VerificationSMSParams{
    PhoneNumber:     "+13035551234",
    VerifyProfileID: "4900017a-e7c8-e79e-0a7c-0d98f49b09cc",
  })
  if err != nil {
    panic(err)
  }
  fmt.Printf("Verification ID: %s\n", verification.Data.ID)
  fmt.Printf("Status: %s\n", verification.Data.Status) // "pending"
}

Java

package com.telnyx.example;

import com.telnyx.sdk.client.TelnyxClient;
import com.telnyx.sdk.client.okhttp.TelnyxOkHttpClient;
import com.telnyx.sdk.models.verify.VerificationParams;
import com.telnyx.sdk.models.verify.VerificationResponse;

public final class Main {
    public static void main(String[] args) {
        TelnyxClient client = TelnyxOkHttpClient.fromEnv();

        VerificationParams params = VerificationParams.builder()
            .phoneNumber("+13035551234")
            .verifyProfileId("4900017a-e7c8-e79e-0a7c-0d98f49b09cc")
            .build();

        VerificationResponse response = client.verifications().sms(params);
        System.out.println("Verification ID: " + response.getId());
        System.out.println("Status: " + response.getStatus()); // "pending"
    }
}

.NET

using Telnyx;

TelnyxConfiguration.SetApiKey(Environment.GetEnvironmentVariable("TELNYX_API_KEY"));

var service = new VerificationService();
var response = await service.SendSmsAsync(new VerificationSmsOptions
{
    PhoneNumber = "+13035551234",
    VerifyProfileId = "4900017a-e7c8-e79e-0a7c-0d98f49b09cc"
});

Console.WriteLine($"Verification ID: {response.Data.Id}");
Console.WriteLine($"Status: {response.Data.Status}"); // "pending"

PHP

<?php
require_once 'vendor/autoload.php';

\Telnyx\Telnyx::setApiKey(getenv('TELNYX_API_KEY'));

$verification = \Telnyx\Verification::create([
    'phone_number' => '+13035551234',
    'verify_profile_id' => '4900017a-e7c8-e79e-0a7c-0d98f49b09cc',
    'type' => 'sms'
]);

echo "Verification ID: " . $verification->id . "\n";
echo "Status: " . $verification->status . "\n"; // "pending"

User experience: The user receives a text message with a numeric code (e.g., “Your verification code is: 17686”). They enter this code in your application. Call verification speaks the code aloud when the user answers. Useful when the user cannot receive SMS (landlines, VoIP) or in regions with unreliable SMS delivery. Profile configuration for call: When creating your verify profile, include the call configuration:

curl --location --request POST 'https://api.telnyx.com/v2/verify_profiles' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--data-raw '{
    "name": "my-app-call-verify",
    "language": "en-US",
    "call": {
        "default_timeout_secs": 600
    }
}'

Initiate a call verification:

curl

curl -X POST \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --data '{"phone_number":"+13035551234","verify_profile_id":"4900017a-e7c8-e79e-0a7c-0d98f49b09cc"}' \
  https://api.telnyx.com/v2/verifications/call

Node

const verification = await client.verifications.triggerCall({
  phone_number: '+13035551234',
  verify_profile_id: '4900017a-e7c8-e79e-0a7c-0d98f49b09cc'
});

console.log('Verification ID:', verification.data.id);
console.log('Type:', verification.data.type); // "call"

Python

verification = client.verifications.trigger_call(
    phone_number="+13035551234",
    verify_profile_id="4900017a-e7c8-e79e-0a7c-0d98f49b09cc"
)

print(f"Verification ID: {verification.data.id}")
print(f"Type: {verification.data.type}")  # "call"

Ruby

verification = client.verifications.call(
  phone_number: "+13035551234",
  verify_profile_id: "4900017a-e7c8-e79e-0a7c-0d98f49b09cc"
)

puts "Verification ID: #{verification.id}"
puts "Type: #{verification.type}" # "call"

verification, err := client.Verifications.Call(context.TODO(), telnyx.VerificationCallParams{
  PhoneNumber:     "+13035551234",
  VerifyProfileID: "4900017a-e7c8-e79e-0a7c-0d98f49b09cc",
})
if err != nil {
  panic(err)
}
fmt.Printf("Verification ID: %s\n", verification.Data.ID)

Java

VerificationResponse response = client.verifications().call(
    VerificationParams.builder()
        .phoneNumber("+13035551234")
        .verifyProfileId("4900017a-e7c8-e79e-0a7c-0d98f49b09cc")
        .build()
);
System.out.println("Verification ID: " + response.getId());

.NET

var response = await service.SendCallAsync(new VerificationCallOptions
{
    PhoneNumber = "+13035551234",
    VerifyProfileId = "4900017a-e7c8-e79e-0a7c-0d98f49b09cc"
});

Console.WriteLine($"Verification ID: {response.Data.Id}");

PHP

$verification = \Telnyx\Verification::create([
    'phone_number' => '+13035551234',
    'verify_profile_id' => '4900017a-e7c8-e79e-0a7c-0d98f49b09cc',
    'type' => 'call'
]);

echo "Verification ID: " . $verification->id . "\n";

User experience: The user receives a phone call. An automated voice reads the verification code aloud (e.g., “Your verification code is 1-7-6-8-6”). The code is repeated twice. The user then enters the code in your application. DTMF confirmation: You can optionally enable DTMF confirmation, where the user enters the code on their phone keypad during the call instead of typing it in your app. See the DTMF Confirmation guide for details.

Example response (all methods)

{
  "data": {
    "created_at": "2020-09-14T17:03:32.965812",
    "id": "12ade33a-21c0-473b-b055-b3c836e1c292",
    "phone_number": "+13035551234",
    "record_type": "verification",
    "status": "pending",
    "timeout_secs": 300,
    "verify_profile_id": "4900017a-e7c8-e79e-0a7c-0d98f49b09cc",
    "type": "sms",
    "updated_at": "2020-09-14T17:03:32.965812"
  }
}

Choosing the right verification method

Feature	SMS	Call	Flashcall
Delivery speed	1–5 seconds	10–20 seconds (ring + answer)	2–5 seconds
User interaction	Read code, type it in	Listen to code, type it in	Automatic (app reads caller ID)
Works on web	✅ Yes	✅ Yes	❌ No (mobile only)
Works on landlines	❌ No	✅ Yes	❌ No
Cost	Per-message rate	Per-minute rate	Per-call rate (very short)
Global coverage	Widest	Wide	Limited
Accessibility	Good	Best (audio)	App-dependent
Best for	General purpose	Landlines, accessibility	Mobile apps with auto-read

Fallback strategy: Configure multiple methods in your verify profile. Start with SMS (fastest and widest coverage), fall back to call if SMS fails. For mobile apps, consider flashcall as a zero-friction primary method with SMS as fallback.

Verify a 2FA code

The user provides the code they received (via SMS or call). Submit it to Telnyx to verify it matches:

curl

curl -X POST \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --data '{"code":"17686", "verify_profile_id": "4900017a-e7c8-e79e-0a7c-0d98f49b09cc"}' \
  https://api.telnyx.com/v2/verifications/by_phone_number/+13035551234/actions/verify

Node

const result = await client.verifications.byPhoneNumber.actions.verify(
  '+13035551234',
  {
    code: '17686',
    verify_profile_id: '4900017a-e7c8-e79e-0a7c-0d98f49b09cc',
  }
);

if (result.data.response_code === 'accepted') {
  console.log('Verification successful!');
} else {
  console.log('Verification failed:', result.data.response_code);
}

Python

result = client.verifications.by_phone_number.actions.verify(
    "+13035551234",
    code="17686",
    verify_profile_id="4900017a-e7c8-e79e-0a7c-0d98f49b09cc"
)

if result.data.response_code == "accepted":
    print("Verification successful!")
else:
    print(f"Verification failed: {result.data.response_code}")

Ruby

result = client.verifications.verify(
  "+13035551234",
  code: "17686",
  verify_profile_id: "4900017a-e7c8-e79e-0a7c-0d98f49b09cc"
)

if result.response_code == "accepted"
  puts "Verification successful!"
else
  puts "Verification failed: #{result.response_code}"
end

result, err := client.Verifications.Verify(context.TODO(), "+13035551234", telnyx.VerificationVerifyParams{
  Code:            "17686",
  VerifyProfileID: "4900017a-e7c8-e79e-0a7c-0d98f49b09cc",
})
if err != nil {
  panic(err)
}
if result.Data.ResponseCode == "accepted" {
  fmt.Println("Verification successful!")
} else {
  fmt.Printf("Verification failed: %s\n", result.Data.ResponseCode)
}

Java

VerifyResponse result = client.verifications().verify(
    "+13035551234",
    VerifyParams.builder()
        .code("17686")
        .verifyProfileId("4900017a-e7c8-e79e-0a7c-0d98f49b09cc")
        .build()
);

if ("accepted".equals(result.getResponseCode())) {
    System.out.println("Verification successful!");
} else {
    System.out.println("Verification failed: " + result.getResponseCode());
}

.NET

var result = await service.VerifyAsync("+13035551234", new VerifyCodeOptions
{
    Code = "17686",
    VerifyProfileId = "4900017a-e7c8-e79e-0a7c-0d98f49b09cc"
});

if (result.Data.ResponseCode == "accepted")
    Console.WriteLine("Verification successful!");
else
    Console.WriteLine($"Verification failed: {result.Data.ResponseCode}");

PHP

$result = \Telnyx\Verification::verify('+13035551234', [
    'code' => '17686',
    'verify_profile_id' => '4900017a-e7c8-e79e-0a7c-0d98f49b09cc'
]);

if ($result->response_code === 'accepted') {
    echo "Verification successful!\n";
} else {
    echo "Verification failed: " . $result->response_code . "\n";
}

Example response

{
  "data": {
    "phone_number": "+13035551234",
    "response_code": "accepted"
  }
}

A response_code of "accepted" confirms the code matches. Other possible values:

Response Code	Meaning
`accepted`	Code is correct - verification successful
`rejected`	Code is incorrect
`expired`	Verification timed out (exceeded `timeout_secs`)
`max_attempts_exceeded`	Too many incorrect attempts

Telnyx Verify supports webhooks to receive instant notifications when users complete verification, eliminating the need for polling. This enables event-driven workflows for faster user experiences. Learn more: Receiving Webhooks for Telnyx Verify

Next steps

Now that you’ve completed a basic verification flow, explore these guides to build a production-ready implementation: Create branded verification messages that match your app’s voice and compliance requirements. Protect against SMS pumping, brute force attacks, and other verification fraud. Receive real-time notifications when verifications complete or expire. Complete login, registration, and payment verification flow implementations.

DTMF confirmation

Source: https://developers.telnyx.com/docs/identity/verify/dtmf-confirm.md

DTMF confirmation calls a phone number, plays a TTS prompt, and collects a single keypress (1) to confirm ownership. No verification code is generated — the keypress is the confirmation. The POST /verifications/{id}/actions/verify endpoint is not used. Verification completes on the call itself. DTMF confirmation is unique to Telnyx — Twilio and Vonage Verify APIs only support code-based voice verification (read a code, then type it). Single-keypress confirmation reduces user friction and works on landlines.

Flow

Outcome	Trigger	Status
Confirmed	Digit `1` pressed	`accepted`
Rejected	Wrong digit	`invalid`
Timed out	No keypress (10s)	`expired`
Failed	Call not answered	`error`

Up to 3 attempts per call. After 3 wrong digits, the call ends with status invalid.

Use cases

Confirm ownership before allowing a number as outbound Caller ID. Verify numbers that cannot receive SMS. Single keypress instead of reading and typing a code. Confirm phone ownership without code entry.

Create a verify profile

Create a profile with dtmf_confirm settings. This can be combined with other verification types (SMS, call) on the same profile.

curl

curl -X POST https://api.telnyx.com/v2/verify_profiles \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -d '{
    "name": "caller-id-verification",
    "language": "en-US",
    "dtmf_confirm": {
      "default_timeout_secs": 300
    }
  }'

Python

import os
import telnyx

telnyx.api_key = os.environ["TELNYX_API_KEY"]

profile = telnyx.VerifyProfile.create(
    name="caller-id-verification",
    language="en-US",
    dtmf_confirm={"default_timeout_secs": 300},
)
profile_id = profile.id

Node

const telnyx = require('telnyx')(process.env.TELNYX_API_KEY);

const profile = await telnyx.verifyProfiles.create({
  name: 'caller-id-verification',
  language: 'en-US',
  dtmf_confirm: { default_timeout_secs: 300 },
});
const profileId = profile.data.id;

Ruby

require 'telnyx'

Telnyx.api_key = ENV['TELNYX_API_KEY']

profile = Telnyx::VerifyProfile.create(
  name: 'caller-id-verification',
  language: 'en-US',
  dtmf_confirm: { default_timeout_secs: 300 }
)
profile_id = profile.id

package main

import (
    "os"
    telnyx "github.com/telnyx/telnyx-go"
)

func main() {
    client := telnyx.NewClient(os.Getenv("TELNYX_API_KEY"))

    profile, _ := client.VerifyProfiles.Create(&telnyx.VerifyProfileParams{
        Name:     "caller-id-verification",
        Language: "en-US",
        DTMFConfirm: &telnyx.DTMFConfirmSettings{
            DefaultTimeoutSecs: 300,
        },
    })
    profileID := profile.ID
}

Java

import com.telnyx.sdk.*;
import com.telnyx.sdk.api.VerifyApi;
import com.telnyx.sdk.model.*;

ApiClient client = Configuration.getDefaultApiClient();
client.setBearerToken(System.getenv("TELNYX_API_KEY"));

VerifyApi api = new VerifyApi(client);
CreateVerifyProfileRequest request = new CreateVerifyProfileRequest()
    .name("caller-id-verification")
    .language("en-US")
    .dtmfConfirm(new DTMFConfirmSettings().defaultTimeoutSecs(300));

VerifyProfileResponse profile = api.createVerifyProfile(request);
String profileId = profile.getData().getId();

.NET

using Telnyx;

TelnyxConfiguration.SetApiKey(Environment.GetEnvironmentVariable("TELNYX_API_KEY"));

var service = new VerifyProfileService();
var profile = service.Create(new VerifyProfileCreateOptions
{
    Name = "caller-id-verification",
    Language = "en-US",
    DtmfConfirm = new DtmfConfirmSettings
    {
        DefaultTimeoutSecs = 300
    }
});
var profileId = profile.Id;

PHP

require 'vendor/autoload.php';

\Telnyx\Telnyx::setApiKey(getenv('TELNYX_API_KEY'));

$profile = \Telnyx\VerifyProfile::create([
    'name' => 'caller-id-verification',
    'language' => 'en-US',
    'dtmf_confirm' => ['default_timeout_secs' => 300],
]);
$profileId = $profile->id;

The returned id is required for verification requests.

Trigger verification

curl

curl -X POST https://api.telnyx.com/v2/verifications/dtmf_confirm \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -d '{
    "phone_number": "+13035551234",
    "verify_profile_id": "YOUR_PROFILE_ID"
  }'

Python

verification = telnyx.Verification.create(
    phone_number="+13035551234",
    verify_profile_id=profile_id,
    type="dtmf_confirm",
)

Node

const verification = await telnyx.verifications.create({
  phone_number: '+13035551234',
  verify_profile_id: profileId,
  type: 'dtmf_confirm',
});

Ruby

verification = Telnyx::Verification.create(
  phone_number: '+13035551234',
  verify_profile_id: profile_id,
  type: 'dtmf_confirm'
)

verification, _ := client.Verifications.Create(&telnyx.VerificationParams{
    PhoneNumber:     "+13035551234",
    VerifyProfileID: profileID,
    Type:            "dtmf_confirm",
})

Java

CreateVerificationRequest verReq = new CreateVerificationRequest()
    .phoneNumber("+13035551234")
    .verifyProfileId(profileId)
    .type(CreateVerificationRequest.TypeEnum.DTMF_CONFIRM);

VerificationResponse ver = api.createVerification(verReq);

.NET

var verService = new VerificationService();
var verification = verService.Create(new VerificationCreateOptions
{
    PhoneNumber = "+13035551234",
    VerifyProfileId = profileId,
    Type = "dtmf_confirm"
});

PHP

$verification = \Telnyx\Verification::create([
    'phone_number' => '+13035551234',
    'verify_profile_id' => $profileId,
    'type' => 'dtmf_confirm',
]);

Response

{
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "phone_number": "+13035551234",
    "record_type": "verification",
    "status": "pending",
    "type": "dtmf_confirm",
    "timeout_secs": 300,
    "verify_profile_id": "YOUR_PROFILE_ID",
    "created_at": "2026-02-20T15:30:00.000000",
    "updated_at": "2026-02-20T15:30:00.000000"
  }
}

Default TTS prompt:

“This is a verification call to confirm that this phone number is going to be used as a Caller ID for outbound calls. If you did not request this verification, or if someone is asking you to accept this call, please ignore this message. If you did request this verification, please press 1.”

The TTS language is determined by the language field on the Verify Profile (default: en-US).

Handle the result

Verification completes on the call — no verify endpoint call needed. Receive the outcome via webhooks.

Accepted (digit `1` pressed)

{
  "data": {
    "event_type": "verification.complete",
    "payload": {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "phone_number": "+13035551234",
      "status": "accepted",
      "type": "dtmf_confirm",
      "verify_profile_id": "YOUR_PROFILE_ID"
    }
  }
}

Failed (wrong digit, timeout, or call failure)

{
  "data": {
    "event_type": "verification.complete",
    "payload": {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "phone_number": "+13035551234",
      "status": "invalid",
      "type": "dtmf_confirm",
      "verify_profile_id": "YOUR_PROFILE_ID"
    }
  }
}

Polling alternative

curl https://api.telnyx.com/v2/verifications/{verification_id} \
  -H "Authorization: Bearer $TELNYX_API_KEY"

Complete example

Full flow: create profile, trigger verification, handle webhook.

import os
import telnyx
from flask import Flask, request, jsonify

telnyx.api_key = os.environ["TELNYX_API_KEY"]
app = Flask(__name__)

# Create profile (once)
profile = telnyx.VerifyProfile.create(
    name="dtmf-verification",
    language="en-US",
    dtmf_confirm={"default_timeout_secs": 300},
)

# Trigger verification
verification = telnyx.Verification.create(
    phone_number="+13035551234",
    verify_profile_id=profile.id,
    type="dtmf_confirm",
)
print(f"Verification {verification.id} — {verification.status}")

@app.route("/webhooks/verify", methods=["POST"])
def handle_webhook():
    payload = request.json["data"]["payload"]

    if payload["status"] == "accepted":
        print(f"✅ {payload['phone_number']} verified")
    else:
        print(f"❌ {payload['phone_number']} failed: {payload['status']}")

    return jsonify({"status": "ok"}), 200

app.run(port=5000)

const express = require('express');
const telnyx = require('telnyx')(process.env.TELNYX_API_KEY);

const app = express();
app.use(express.json());

(async () => {
  // Create profile (once)
  const profile = await telnyx.verifyProfiles.create({
    name: 'dtmf-verification',
    language: 'en-US',
    dtmf_confirm: { default_timeout_secs: 300 },
  });

  // Trigger verification
  const verification = await telnyx.verifications.create({
    phone_number: '+13035551234',
    verify_profile_id: profile.data.id,
    type: 'dtmf_confirm',
  });
  console.log(`Verification ${verification.data.id} — ${verification.data.status}`);

  // Handle webhook
  app.post('/webhooks/verify', (req, res) => {
    const { phone_number, status } = req.body.data.payload;

    if (status === 'accepted') {
      console.log(`✅ ${phone_number} verified`);
    } else {
      console.log(`❌ ${phone_number} failed: ${status}`);
    }

    res.json({ status: 'ok' });
  });

  app.listen(5000, () => console.log('Webhook server on :5000'));
})();

require 'telnyx'
require 'sinatra'
require 'json'

Telnyx.api_key = ENV['TELNYX_API_KEY']

# Create profile (once)
profile = Telnyx::VerifyProfile.create(
  name: 'dtmf-verification',
  language: 'en-US',
  dtmf_confirm: { default_timeout_secs: 300 }
)

# Trigger verification
verification = Telnyx::Verification.create(
  phone_number: '+13035551234',
  verify_profile_id: profile.id,
  type: 'dtmf_confirm'
)
puts "Verification #{verification.id} — #{verification.status}"

# Handle webhook
post '/webhooks/verify' do
  payload = JSON.parse(request.body.read)['data']['payload']

  if payload['status'] == 'accepted'
    puts "✅ #{payload['phone_number']} verified"
  else
    puts "❌ #{payload['phone_number']} failed: #{payload['status']}"
  end

  { status: 'ok' }.to_json
end

package main

import (
    "encoding/json"
    "fmt"
    "net/http"
    "os"

    telnyx "github.com/telnyx/telnyx-go"
)

func main() {
    client := telnyx.NewClient(os.Getenv("TELNYX_API_KEY"))

    // Create profile (once)
    profile, _ := client.VerifyProfiles.Create(&telnyx.VerifyProfileParams{
        Name:     "dtmf-verification",
        Language: "en-US",
        DTMFConfirm: &telnyx.DTMFConfirmSettings{
            DefaultTimeoutSecs: 300,
        },
    })

    // Trigger verification
    ver, _ := client.Verifications.Create(&telnyx.VerificationParams{
        PhoneNumber:     "+13035551234",
        VerifyProfileID: profile.ID,
        Type:            "dtmf_confirm",
    })
    fmt.Printf("Verification %s — %s\n", ver.ID, ver.Status)

    // Handle webhook
    http.HandleFunc("/webhooks/verify", func(w http.ResponseWriter, r *http.Request) {
        var event struct {
            Data struct {
                Payload struct {
                    PhoneNumber string `json:"phone_number"`
                    Status      string `json:"status"`
                } `json:"payload"`
            } `json:"data"`
        }
        json.NewDecoder(r.Body).Decode(&event)

        p := event.Data.Payload
        if p.Status == "accepted" {
            fmt.Printf("✅ %s verified\n", p.PhoneNumber)
        } else {
            fmt.Printf("❌ %s failed: %s\n", p.PhoneNumber, p.Status)
        }
        w.Write([]byte(`{"status":"ok"}`))
    })

    http.ListenAndServe(":5000", nil)
}

Verification type comparison

Feature	SMS	Call	Flash Call	DTMF Confirm
User action	Type code	Listen + type code	None	Press 1
Code generated	Yes	Yes	Yes (caller ID)	No
Verify endpoint	Required	Required	Required	Not needed
Landline support	No	Yes	No	Yes
Fraud risk	SIM swap, interception	Low	Low	Low
Competitor support	Twilio, Vonage	Twilio, Vonage	Twilio	Telnyx only

Troubleshooting

Verification times out with status expired. Implement a retry with delay, or fall back to SMS. Up to 3 attempts per call. After 3 failures, status is invalid. Trigger a new verification to retry. Call was not answered and no webhook received. Verify the webhook URL is configured and reachable. Poll the status endpoint as fallback. The prompt is fixed to the standard verification message. Voice and language are determined by the Verify Profile’s language setting. Custom prompt text is not yet supported. Standard Verify API rate limits apply. Avoid triggering multiple concurrent verifications for the same phone number — the previous call must complete or time out first.

Next steps

Real-time verification status updates. Branded verification messages for SMS and call types. Full API specification. SMS and call verification guide.

Custom templates

Source: https://developers.telnyx.com/docs/identity/verify/custom-templates.md

Telnyx Verify now enables you to create and register your own verification message templates instantly. This feature allows you to build compliant, branded one-time password (OTP) messages that match your brand voice while maintaining security standards.

Overview

Custom templates give you complete control over your verification messaging. Instead of using pre-built templates, you can create personalized messages that:

Align with your brand guidelines and tone of voice.
Include industry-specific security warnings and disclaimers.
Maintain compliance with regulatory requirements.
Deploy instantly without manual approval processes.

When to use custom templates

Use custom templates when:

You need branded verification messages that match your company’s voice.
Your industry requires specific compliance language in OTP messages.
You want to include custom security warnings or instructions.
You need different templates for different user segments or regions.

Use pre-built templates when:

You’re getting started quickly and don’t need customization.
Standard verification messages meet your requirements.
You want to minimize setup time.

Template variables

All verification templates support the following variables that will be automatically replaced when sending verifications:

{{app_name}} - Your application name as configured in the verify profile.
{{code}} - The verification code sent to the user.

Creating custom templates

Use the Telnyx API to create custom verification message templates.

Create a custom template

curl -L 'https://api.telnyx.com/v2/verify_profiles/templates' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -d '{
    "text": "Your {{app_name}} verification code is {{code}}. Do not share this code."
  }'

Example response

{
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "text": "Your {{app_name}} verification code is {{code}}. Do not share this code."
  }
}

Save the template id returned in the response. You’ll need this ID to reference the template when creating verify profiles. For complete API details, see the Create Message Template API reference.

Real-world template examples

Here are industry-specific template examples to inspire your custom messaging:

E-commerce and retail

Your {{app_name}} verification code is {{code}}. Complete your purchase securely.

Banking and finance

{{code}} is your {{app_name}} security code. Never share this with anyone, including our staff.

Healthcare and telemedicine

Your {{app_name}} appointment verification code: {{code}}. If you didn't request this, contact support immediately.

Welcome to {{app_name}}! Your verification code is {{code}}. Start connecting with friends now.

Delivery and logistics

Your {{app_name}} delivery confirmation code is {{code}}. Track your package now.

Travel and hospitality

{{code}} is your {{app_name}} booking verification code.

Using custom templates in verify profiles

Once you’ve created a custom template, reference its ID when creating or updating a verify profile.

Example: Create verify profile with custom template

curl -L 'https://api.telnyx.com/v2/verify_profiles' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -d '{
    "name": "my-app-verification",
    "language": "en-US",
    "sms": {
      "messaging_template_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "whitelisted_destinations": ["US", "CA"],
      "default_timeout_secs": 300,
      "code_length": 6
    }
  }'

The messaging_template_id field references your custom template. When you send verifications using this profile, your custom template will be used instead of the default.

Updating custom templates

You can update existing custom templates to refine messaging or fix errors.

Update a template

curl -L -X PATCH 'https://api.telnyx.com/v2/verify_profiles/templates/a1b2c3d4-e5f6-7890-abcd-ef1234567890' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -d '{
    "text": "Your {{app_name}} verification code is {{code}}. Contact support if you did not request this."
  }'

Example response

{
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "text": "Your {{app_name}} verification code is {{code}}. Contact support if you did not request this."
  }
}

Updating a template affects all verify profiles that reference it. Test template changes carefully before updating production templates. For complete API details, see the Update Message Template API reference.

Best practices

Keep messages concise

SMS messages have character limits. Keep your templates under 160 characters when possible to avoid message splitting and additional costs.

Include security warnings

For sensitive use cases like banking or healthcare, include warnings about not sharing codes:

Never share this code with anyone, including our staff.
If you didn't request this, contact support immediately.

Test before production

Always test new templates in a development environment before using them in production verify profiles. Send test verifications to confirm:

Variables are replaced correctly.
Message formatting appears as expected.
Character count is within limits.
Links or special characters display properly.

Follow compliance guidelines

Ensure your templates comply with:

Industry regulations (HIPAA, PCI-DSS, GDPR, etc.).
Carrier requirements for SMS messaging.
Local laws regarding verification messages.
Your organization’s security policies.

Consider localization

If you serve multiple regions, create separate templates for different languages and cultures. Use the verify profile’s language parameter to organize templates by locale.

Next steps

Learn how to send verifications: Telnyx Verify quickstart
Configure webhooks for verification events: Receiving webhooks
View the complete Verify API reference: Verify API documentation

Webhooks

Source: https://developers.telnyx.com/docs/identity/verify/receiving-webhooks.md

You can choose to be notified about events on your send verifications by configuring webhooks on your verify profile.

Verify delivery status updates

The Telnyx Verify Service will attempt to notify you about the following delivery events for the send verification request:

verify.sent
verify.failed
verify.delivered

Delivery status Payload

Here is an example of a webhook event where a delivery receipt is returned to the sender after sending a verification:

{
  "data": {
    "event_type": "verify.delivered",
    "id": "3bb6321b-abd5-4d60-8cf8-1e6026bb1c41",
    "occurred_at": "2025-10-08T17:16:09.602+00:00",
    "payload": {
      "created_at": "2025-10-08T17:16:08.436941",
      "custom_code": "25565",
      "delivery_status": "delivered",
      "extension": null,
      "failed_attempts": 0,
      "id": "010d9dee-d86d-47d0-8d6c-20c0f95a79ec",
      "mccmnc": null,
      "phone_number": "+13125000000",
      "profile_id": "49000192-1bdb-c56f-3de7-e008ef6da16b",
      "record_type": "verification",
      "status": "pending",
      "timeout_secs": null,
      "type": "sms",
      "updated_at": "2025-10-08T17:16:09.592765"
    },
    "record_type": "event"
  },
  "meta": {
    "attempt": 1,
    "delivered_to": "https://webhook.site/af3a92e7-e150-442c-9fe6-61658ce26b1a"
  }
}

Delivery statuses

Delivery Status Description sent The verification has been sent to the upstream provider. delivered The upstream provider has confirmed delivery of the verification. sending_failed Telnyx has failed to send the verification to the upstream provider. Please reach out to our support if you have received this status. delivery_failed The upstream provider has failed to send the verification to the receiver. Please reach out to our support if you have received this status. delivery_unconfirmed There is no indication whether or not the verification has reached the receiver. Please reach out to our support if you have received this status

Real-time verification status updates

Telnyx Verify now supports webhooks for instant verification status notifications, eliminating the need to poll the API for verification completion.

Benefits

Eliminates polling - No need to repeatedly check verification status through API calls.
Event-driven workflow - React immediately to verification state changes in real-time.
Faster user experience - Process verification completions instantly without delays.
Improved efficiency - Reduces server load and unnecessary API requests.

Configure webhooks on your Verify profile to receive real-time updates when verifications complete. For specific webhook event types, payload structures, and configuration details, refer to the Telnyx API documentation or contact Telnyx support.

Telnyx Webhook IPs

If you use an ACL or Firewall on your network, make sure you whitelist the following subnet(s): 192.76.120.192/27

Security Best Practices

Source: https://developers.telnyx.com/docs/identity/verify/security-best-practices.md

Verification flows are a high-value target for attackers. SMS pumping, toll fraud, brute-force code guessing, and social engineering can cost you money and compromise user accounts. This guide covers practical defenses you should implement alongside Telnyx Verify.

Threat overview

Threat	Description	Impact
SMS pumping	Attackers trigger thousands of SMS verifications to premium-rate numbers	Inflated costs, sometimes $10K+ per incident
Toll fraud (IRSF)	Exploiting call verification to generate revenue on premium international numbers	Per-minute charges on fraudulent calls
Brute-force attacks	Systematically guessing verification codes	Account takeover
Code interception	SIM swapping, SS7 attacks, malware intercepting SMS	Account compromise
Enumeration	Using verification endpoints to check if phone numbers exist in your system	Privacy leak, targeted attacks

Rate limiting

Rate limiting is your first line of defense against abuse. Apply limits at multiple layers.

Per-phone-number limits

Restrict how many verification attempts a single phone number can trigger within a time window.

Node

import { RateLimiterMemory } from 'rate-limiter-flexible';

// Max 3 verification requests per phone number per 10 minutes
const phoneLimiter = new RateLimiterMemory({
  points: 3,
  duration: 600, // 10 minutes
});

async function requestVerification(phoneNumber) {
  try {
    await phoneLimiter.consume(phoneNumber);
    // Proceed with Telnyx Verify API call
  } catch (rejRes) {
    const retryAfter = Math.ceil(rejRes.msBeforeNext / 1000);
    throw new Error(`Too many attempts. Try again in ${retryAfter} seconds.`);
  }
}

Python

from datetime import datetime, timedelta

# Simple in-memory rate limiter (use Redis in production)
verification_attempts = {}

def check_rate_limit(phone_number, max_attempts=3, window_minutes=10):
    now = datetime.utcnow()
    cutoff = now - timedelta(minutes=window_minutes)

    # Clean old attempts
    attempts = verification_attempts.get(phone_number, [])
    attempts = [t for t in attempts if t > cutoff]

    if len(attempts) >= max_attempts:
        raise Exception(f"Too many attempts. Try again later.")

    attempts.append(now)
    verification_attempts[phone_number] = attempts
    return True

package main

import (
  "fmt"
  "sync"
  "time"
)

type RateLimiter struct {
  mu       sync.Mutex
  attempts map[string][]time.Time
  max      int
  window   time.Duration
}

func NewRateLimiter(max int, window time.Duration) *RateLimiter {
  return &RateLimiter{
    attempts: make(map[string][]time.Time),
    max:      max,
    window:   window,
  }
}

func (rl *RateLimiter) Allow(key string) error {
  rl.mu.Lock()
  defer rl.mu.Unlock()

  cutoff := time.Now().Add(-rl.window)
  var valid []time.Time
  for _, t := range rl.attempts[key] {
    if t.After(cutoff) {
      valid = append(valid, t)
    }
  }

  if len(valid) >= rl.max {
    return fmt.Errorf("too many attempts, try again later")
  }

  rl.attempts[key] = append(valid, time.Now())
  return nil
}

Per-IP address limits

Prevent a single IP from triggering verifications for many different numbers (a hallmark of SMS pumping):

Node

// Max 10 verification requests per IP per hour
const ipLimiter = new RateLimiterMemory({
  points: 10,
  duration: 3600,
});

app.post('/verify/request', async (req, res) => {
  const clientIp = req.ip;
  try {
    await ipLimiter.consume(clientIp);
    await phoneLimiter.consume(req.body.phone_number);
    // Proceed with verification
  } catch {
    res.status(429).json({ error: 'Too many requests' });
  }
});

Python

from flask import Flask, request, jsonify
from flask_limiter import Limiter
from flask_limiter.util import get_remote_address

app = Flask(__name__)
limiter = Limiter(app=app, key_func=get_remote_address)

@app.route("/verify/request", methods=["POST"])
@limiter.limit("10 per hour")
def request_verification():
    phone_number = request.json["phone_number"]
    check_rate_limit(phone_number)
    # Proceed with Telnyx Verify API call
    return jsonify(success=True)

Recommended limits

Scope	Limit	Window
Per phone number	3 attempts	10 minutes
Per phone number	5 attempts	1 hour
Per IP address	10 attempts	1 hour
Per account/session	5 attempts	1 hour
Global (all numbers)	Monitor for spikes	Continuous

SMS pumping prevention

SMS pumping is the most costly fraud vector for verification flows. Attackers abuse your send endpoint to generate SMS revenue on number ranges they control.

Detection signals

Watch for these patterns:

Sequential numbers — Verification requests for +1234500001, +1234500002, +1234500003…
Unusual country codes — Spike in verifications to countries you don’t serve
High failure rate — Many verifications triggered but never completed
Burst traffic — Sudden spike in verification requests from a single source

Defenses

Configure whitelisted_destinations on your Verify profile to only allow countries where your users are:

curl -X PATCH "https://api.telnyx.com/v2/verify_profiles/YOUR_PROFILE_ID" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sms": {
      "whitelisted_destinations": ["US", "CA", "GB"]
    }
  }'

Don’t expose your verification endpoint to unauthenticated users. Require at least a session or account to trigger a verification. Place a CAPTCHA (reCAPTCHA, hCaptcha, Turnstile) before the phone number input to block automated submissions. Set up alerts for unusual verification volume:

// Track verification requests per minute
const verifyCount = new Map();

function trackVerification() {
  const minute = Math.floor(Date.now() / 60000);
  verifyCount.set(minute, (verifyCount.get(minute) || 0) + 1);

  if (verifyCount.get(minute) > 100) {
    // Alert: possible SMS pumping attack
    alertOps('Verification spike detected: ' + verifyCount.get(minute) + '/min');
  }
}

Code security

Use appropriate code length

Longer codes are harder to brute-force but harder for users to enter. Balance security and usability:

Code Length	Combinations	Brute-force time (3 attempts/min)	Recommendation
4 digits	10,000	~55 hours	Low security only
5 digits	100,000	~23 days	Default — good balance
6 digits	1,000,000	~231 days	High security applications

Configure code length in your Verify profile:

curl -X PATCH "https://api.telnyx.com/v2/verify_profiles/YOUR_PROFILE_ID" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sms": {
      "code_length": 6
    }
  }'

Set appropriate timeouts

Short timeouts reduce the window for brute-force attacks:

curl -X PATCH "https://api.telnyx.com/v2/verify_profiles/YOUR_PROFILE_ID" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sms": {
      "default_timeout_secs": 300
    },
    "call": {
      "default_timeout_secs": 300
    }
  }'

A 5-minute timeout (300 seconds) works well for most applications. Shorter timeouts (120s) add security but may frustrate users on slow networks.

Limit verification attempts

Lock out after too many failed code entries to prevent brute-force:

Node

const failedAttempts = new Map();

async function verifyCode(phoneNumber, code) {
  const attempts = failedAttempts.get(phoneNumber) || 0;

  if (attempts >= 5) {
    throw new Error('Too many failed attempts. Request a new code.');
  }

  const response = await fetch(
    `https://api.telnyx.com/v2/verifications/by_phone_number/${phoneNumber}/actions/verify`,
    {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${process.env.TELNYX_API_KEY}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({ code, verify_profile_id: PROFILE_ID }),
    }
  );
  const result = await response.json();

  if (result.data.response_code === 'accepted') {
    failedAttempts.delete(phoneNumber);
    return true;
  }

  failedAttempts.set(phoneNumber, attempts + 1);
  return false;
}

Python

import requests
import os

failed_attempts = {}  # Use Redis in production

def verify_code(phone_number, code, profile_id):
    attempts = failed_attempts.get(phone_number, 0)

    if attempts >= 5:
        raise Exception("Too many failed attempts. Request a new code.")

    response = requests.post(
        f"https://api.telnyx.com/v2/verifications/by_phone_number/{phone_number}/actions/verify",
        headers={"Authorization": f"Bearer {os.environ['TELNYX_API_KEY']}"},
        json={"code": code, "verify_profile_id": profile_id},
    )
    result = response.json()

    if result["data"]["response_code"] == "accepted":
        failed_attempts.pop(phone_number, None)
        return True

    failed_attempts[phone_number] = attempts + 1
    return False

Prevent number enumeration

Don’t reveal whether a phone number exists in your system through verification responses: ❌ Vulnerable — reveals whether the number is registered:

{ "error": "No account found for this phone number" }

✅ Secure — same response regardless:

{ "message": "If this number is registered, you'll receive a verification code." }

Always return a consistent response and send the verification (or silently drop it) regardless of whether the number exists in your system.

Channel fallback strategy

Use multiple verification channels to improve delivery and security: Start with SMS verification — widest reach and fastest delivery. If SMS isn’t delivered within 30 seconds, offer a voice call option. This helps users on networks with delayed SMS delivery. For supported markets, flashcall verification (where the phone number itself is the code) provides instant verification with no user input required. Configure all three channels on your Verify profile:

curl -X PATCH "https://api.telnyx.com/v2/verify_profiles/YOUR_PROFILE_ID" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sms": {
      "whitelisted_destinations": ["US", "CA"],
      "default_timeout_secs": 300,
      "code_length": 6
    },
    "call": {
      "default_timeout_secs": 300
    },
    "flashcall": {
      "default_timeout_secs": 300
    }
  }'

Webhook security for Verify

Secure your verification webhook endpoint to prevent spoofed delivery notifications:

Allowlist Telnyx IPs — Only accept webhooks from 192.76.120.192/27
Use HTTPS — Never use plain HTTP for webhook endpoints
Validate payload structure — Check for expected fields before processing
Don’t trust client-side status — Always verify through webhooks or API, never trust client-reported verification status

Node

import { createServer } from 'http';
import { networkInterfaces } from 'os';

const TELNYX_WEBHOOK_CIDR = '192.76.120.192/27';

function isFromTelnyx(ip) {
  // In production, use a proper CIDR matching library
  const parts = ip.split('.').map(Number);
  return parts[0] === 192 && parts[1] === 76 &&
         parts[2] === 120 && parts[3] >= 192 && parts[3] <= 223;
}

app.post('/webhooks/verify', (req, res) => {
  const clientIp = req.headers['x-forwarded-for']?.split(',')[0] || req.ip;

  if (!isFromTelnyx(clientIp)) {
    console.warn(`Rejected webhook from unauthorized IP: ${clientIp}`);
    return res.sendStatus(403);
  }

  // Process webhook
  const event = req.body.data;
  if (event.event_type === 'verify.delivered') {
    console.log(`Verification delivered to ${event.payload.phone_number}`);
  }

  res.sendStatus(200);
});

Python

import ipaddress
from flask import Flask, request, jsonify

TELNYX_WEBHOOK_SUBNET = ipaddress.ip_network("192.76.120.192/27")

@app.route("/webhooks/verify", methods=["POST"])
def handle_verify_webhook():
    client_ip = ipaddress.ip_address(
        request.headers.get("X-Forwarded-For", request.remote_addr).split(",")[0].strip()
    )

    if client_ip not in TELNYX_WEBHOOK_SUBNET:
        return jsonify(error="Forbidden"), 403

    event = request.json["data"]
    if event["event_type"] == "verify.delivered":
        print(f"Verification delivered to {event['payload']['phone_number']}")

    return jsonify(success=True), 200

Security checklist

Use this checklist when implementing Telnyx Verify in production:

Next steps

Set up your first verification flow Brand your verification messages Receive real-time verification status updates Advanced fraud prevention strategies

Rate Limiting & Fraud Prevention

Source: https://developers.telnyx.com/docs/identity/verify/rate-limiting-fraud-prevention.md

This guide goes deep on the operational side of protecting your Telnyx Verify integration — server-side rate limiting architectures, geo-fencing, anomaly detection, cost controls, and incident response. For foundational security concepts, see the Security Best Practices guide.

Architecture overview

A robust fraud prevention system layers multiple defenses:

User Request → CAPTCHA → IP Rate Limit → Phone Rate Limit → Geo-fence → Anomaly Check → Telnyx Verify API

Each layer catches different attack patterns. No single defense is sufficient on its own.

Server-side rate limiting with Redis

Production rate limiting requires a distributed store. These examples use Redis for shared state across multiple application instances.

Sliding window rate limiter

Node

import Redis from 'ioredis';

const redis = new Redis(process.env.REDIS_URL);

/**
 * Sliding window rate limiter using Redis sorted sets.
 * @param {string} key - Rate limit key (e.g., phone number or IP)
 * @param {number} maxRequests - Maximum requests allowed
 * @param {number} windowMs - Time window in milliseconds
 * @returns {Promise<{allowed: boolean, remaining: number, retryAfterMs: number}>}
 */
async function checkRateLimit(key, maxRequests, windowMs) {
  const now = Date.now();
  const windowStart = now - windowMs;
  const redisKey = `ratelimit:${key}`;

  const pipeline = redis.pipeline();
  pipeline.zremrangebyscore(redisKey, 0, windowStart);  // Remove expired
  pipeline.zcard(redisKey);                              // Count current
  pipeline.zadd(redisKey, now, `${now}-${Math.random()}`); // Add this request
  pipeline.expire(redisKey, Math.ceil(windowMs / 1000)); // Set TTL

  const results = await pipeline.exec();
  const currentCount = results[1][1];

  if (currentCount >= maxRequests) {
    // Remove the entry we just added
    await redis.zremrangebyscore(redisKey, now, now);
    const oldestEntry = await redis.zrange(redisKey, 0, 0, 'WITHSCORES');
    const retryAfterMs = oldestEntry.length > 1
      ? windowMs - (now - Number(oldestEntry[1]))
      : windowMs;

    return { allowed: false, remaining: 0, retryAfterMs };
  }

  return { allowed: true, remaining: maxRequests - currentCount - 1, retryAfterMs: 0 };
}

// Usage: Multi-layer rate limiting
async function handleVerificationRequest(req) {
  const phone = req.body.phone_number;
  const ip = req.ip;
  const userId = req.user?.id;

  // Layer 1: IP rate limit (10/hour)
  const ipCheck = await checkRateLimit(`ip:${ip}`, 10, 3600000);
  if (!ipCheck.allowed) {
    return { status: 429, retryAfter: ipCheck.retryAfterMs };
  }

  // Layer 2: Phone rate limit (3/10min)
  const phoneCheck = await checkRateLimit(`phone:${phone}`, 3, 600000);
  if (!phoneCheck.allowed) {
    return { status: 429, retryAfter: phoneCheck.retryAfterMs };
  }

  // Layer 3: User rate limit (5/hour)
  if (userId) {
    const userCheck = await checkRateLimit(`user:${userId}`, 5, 3600000);
    if (!userCheck.allowed) {
      return { status: 429, retryAfter: userCheck.retryAfterMs };
    }
  }

  // All checks passed — send verification
  return await sendVerification(phone);
}

Python

import time
import math
import redis
import os
import random

r = redis.Redis.from_url(os.environ.get("REDIS_URL", "redis://localhost:6379"))

def check_rate_limit(key: str, max_requests: int, window_seconds: int) -> dict:
    """Sliding window rate limiter using Redis sorted sets."""
    now = time.time()
    window_start = now - window_seconds
    redis_key = f"ratelimit:{key}"

    pipe = r.pipeline()
    pipe.zremrangebyscore(redis_key, 0, window_start)
    pipe.zcard(redis_key)
    pipe.zadd(redis_key, {f"{now}-{random.random()}": now})
    pipe.expire(redis_key, window_seconds + 1)
    results = pipe.execute()

    current_count = results[1]

    if current_count >= max_requests:
        r.zremrangebyscore(redis_key, now, now)
        oldest = r.zrange(redis_key, 0, 0, withscores=True)
        retry_after = window_seconds - (now - oldest[0][1]) if oldest else window_seconds
        return {"allowed": False, "remaining": 0, "retry_after_seconds": math.ceil(retry_after)}

    return {"allowed": True, "remaining": max_requests - current_count - 1, "retry_after_seconds": 0}

def handle_verification_request(phone_number: str, ip: str, user_id: str = None):
    # Layer 1: IP rate limit (10/hour)
    ip_check = check_rate_limit(f"ip:{ip}", 10, 3600)
    if not ip_check["allowed"]:
        return {"error": "Too many requests", "retry_after": ip_check["retry_after_seconds"]}

    # Layer 2: Phone rate limit (3/10min)
    phone_check = check_rate_limit(f"phone:{phone_number}", 3, 600)
    if not phone_check["allowed"]:
        return {"error": "Too many attempts for this number", "retry_after": phone_check["retry_after_seconds"]}

    # Layer 3: User rate limit (5/hour)
    if user_id:
        user_check = check_rate_limit(f"user:{user_id}", 5, 3600)
        if not user_check["allowed"]:
            return {"error": "Too many requests", "retry_after": user_check["retry_after_seconds"]}

    return send_verification(phone_number)

Ruby

require "redis"

redis = Redis.new(url: ENV["REDIS_URL"] || "redis://localhost:6379")

def check_rate_limit(redis, key, max_requests, window_seconds)
  now = Time.now.to_f
  window_start = now - window_seconds
  redis_key = "ratelimit:#{key}"

  redis.pipelined do |pipe|
    pipe.zremrangebyscore(redis_key, 0, window_start)
    pipe.zcard(redis_key)
    pipe.zadd(redis_key, now, "#{now}-#{rand}")
    pipe.expire(redis_key, window_seconds + 1)
  end => [_, current_count, _, _]

  if current_count >= max_requests
    redis.zremrangebyscore(redis_key, now, now)
    oldest = redis.zrange(redis_key, 0, 0, with_scores: true)
    retry_after = oldest.any? ? window_seconds - (now - oldest[0][1]) : window_seconds
    { allowed: false, remaining: 0, retry_after: retry_after.ceil }
  else
    { allowed: true, remaining: max_requests - current_count - 1, retry_after: 0 }
  end
end

package ratelimit

import (
  "context"
  "fmt"
  "math/rand"
  "time"

  "github.com/redis/go-redis/v9"
)

type Result struct {
  Allowed      bool
  Remaining    int
  RetryAfterMs int64
}

func CheckRateLimit(ctx context.Context, rdb *redis.Client, key string, maxReqs int, window time.Duration) (*Result, error) {
  now := time.Now()
  windowStart := now.Add(-window)
  redisKey := fmt.Sprintf("ratelimit:%s", key)

  pipe := rdb.Pipeline()
  pipe.ZRemRangeByScore(ctx, redisKey, "0", fmt.Sprintf("%f", float64(windowStart.UnixMilli())))
  countCmd := pipe.ZCard(ctx, redisKey)
  member := fmt.Sprintf("%d-%f", now.UnixMilli(), rand.Float64())
  pipe.ZAdd(ctx, redisKey, redis.Z{Score: float64(now.UnixMilli()), Member: member})
  pipe.Expire(ctx, redisKey, window+time.Second)
  _, err := pipe.Exec(ctx)
  if err != nil {
    return nil, err
  }

  count := countCmd.Val()
  if count >= int64(maxReqs) {
    rdb.ZRem(ctx, redisKey, member)
    return &Result{Allowed: false, Remaining: 0, RetryAfterMs: window.Milliseconds()}, nil
  }

  return &Result{Allowed: true, Remaining: maxReqs - int(count) - 1, RetryAfterMs: 0}, nil
}

Geo-fencing

Restrict verifications to countries where your service operates. This is the single most effective defense against SMS pumping.

Configure on Verify profile

curl -X PATCH "https://api.telnyx.com/v2/verify_profiles/YOUR_PROFILE_ID" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sms": {
      "whitelisted_destinations": ["US", "CA", "GB", "AU"]
    }
  }'

Application-level geo-validation

Add server-side validation before calling the API as a defense-in-depth measure:

Node

import { parsePhoneNumber } from 'libphonenumber-js';

const ALLOWED_COUNTRIES = new Set(['US', 'CA', 'GB', 'AU']);

function validatePhoneCountry(phoneNumber) {
  const parsed = parsePhoneNumber(phoneNumber);
  if (!parsed || !parsed.country) {
    throw new Error('Invalid phone number');
  }
  if (!ALLOWED_COUNTRIES.has(parsed.country)) {
    throw new Error('Verification not available in this region');
  }
  return parsed.country;
}

Python

import phonenumbers

ALLOWED_COUNTRIES = {"US", "CA", "GB", "AU"}

def validate_phone_country(phone_number: str) -> str:
    parsed = phonenumbers.parse(phone_number)
    country = phonenumbers.region_code_for_number(parsed)
    if country not in ALLOWED_COUNTRIES:
        raise ValueError("Verification not available in this region")
    return country

High-risk country codes

These country codes are frequently targeted for SMS pumping and toll fraud. Block or add extra scrutiny:

Code	Country	Risk
+232	Sierra Leone	SMS pumping
+225	Côte d’Ivoire	SMS pumping
+233	Ghana	SMS pumping
+234	Nigeria	Mixed (legitimate + fraud)
+260	Zambia	SMS pumping
+256	Uganda	SMS pumping
+880	Bangladesh	Toll fraud
+855	Cambodia	Toll fraud
+856	Laos	Toll fraud
+960	Maldives	Toll fraud
+592	Guyana	Toll fraud

Note: These are statistical patterns, not blanket rules. If you serve users in these countries, implement stronger rate limiting rather than blocking.

Anomaly detection

Build automated detection for suspicious patterns beyond simple rate limits.

Conversion rate monitoring

A healthy verification flow has a 60-80% conversion rate (codes sent vs. codes verified). A rate below 20% may indicate an attack.

Node

class ConversionMonitor {
  constructor(redis, alertCallback) {
    this.redis = redis;
    this.alertCallback = alertCallback;
  }

  async trackSent(phoneNumber) {
    const hour = Math.floor(Date.now() / 3600000);
    await this.redis.incr(`verify:sent:${hour}`);
    await this.redis.expire(`verify:sent:${hour}`, 7200);
  }

  async trackVerified(phoneNumber) {
    const hour = Math.floor(Date.now() / 3600000);
    await this.redis.incr(`verify:verified:${hour}`);
    await this.redis.expire(`verify:verified:${hour}`, 7200);
  }

  async checkConversionRate() {
    const hour = Math.floor(Date.now() / 3600000);
    const sent = parseInt(await this.redis.get(`verify:sent:${hour}`)) || 0;
    const verified = parseInt(await this.redis.get(`verify:verified:${hour}`)) || 0;

    if (sent < 10) return; // Too few samples

    const rate = verified / sent;
    if (rate < 0.2) {
      this.alertCallback({
        message: `Low verification conversion rate: ${(rate * 100).toFixed(1)}%`,
        sent,
        verified,
        hour: new Date(hour * 3600000).toISOString(),
      });
    }
  }
}

Python

import time
import redis as redis_lib

class ConversionMonitor:
    def __init__(self, redis_client, alert_callback):
        self.redis = redis_client
        self.alert = alert_callback

    def _hour_key(self):
        return int(time.time() // 3600)

    def track_sent(self):
        hour = self._hour_key()
        self.redis.incr(f"verify:sent:{hour}")
        self.redis.expire(f"verify:sent:{hour}", 7200)

    def track_verified(self):
        hour = self._hour_key()
        self.redis.incr(f"verify:verified:{hour}")
        self.redis.expire(f"verify:verified:{hour}", 7200)

    def check_conversion_rate(self):
        hour = self._hour_key()
        sent = int(self.redis.get(f"verify:sent:{hour}") or 0)
        verified = int(self.redis.get(f"verify:verified:{hour}") or 0)

        if sent < 10:
            return

        rate = verified / sent
        if rate < 0.2:
            self.alert({
                "message": f"Low verification conversion rate: {rate:.1%}",
                "sent": sent,
                "verified": verified,
            })

Sequential number detection

SMS pumping often uses sequential phone numbers. Detect and block this pattern:

function detectSequentialNumbers(recentNumbers, threshold = 5) {
  if (recentNumbers.length < threshold) return false;

  // Sort by numeric value
  const sorted = recentNumbers
    .map(n => BigInt(n.replace(/\D/g, '')))
    .sort((a, b) => (a < b ? -1 : 1));

  // Check for sequences
  let sequential = 1;
  for (let i = 1; i < sorted.length; i++) {
    if (sorted[i] - sorted[i - 1] <= 3n) {
      sequential++;
      if (sequential >= threshold) return true;
    } else {
      sequential = 1;
    }
  }

  return false;
}

Cost controls

Set spend alerts

Monitor your Telnyx account spending and set alerts at the account level through the Telnyx Portal billing settings.

Implement circuit breakers

Automatically disable verifications when anomalies are detected:

class VerificationCircuitBreaker {
  constructor(redis, maxPerHour = 500) {
    this.redis = redis;
    this.maxPerHour = maxPerHour;
    this.tripped = false;
  }

  async canSend() {
    if (this.tripped) return false;

    const hour = Math.floor(Date.now() / 3600000);
    const count = parseInt(await this.redis.get(`verify:total:${hour}`)) || 0;

    if (count >= this.maxPerHour) {
      this.tripped = true;
      // Alert operations team
      console.error(`Circuit breaker tripped: ${count} verifications in current hour`);
      return false;
    }

    await this.redis.incr(`verify:total:${hour}`);
    await this.redis.expire(`verify:total:${hour}`, 7200);
    return true;
  }

  reset() {
    this.tripped = false;
  }
}

Incident response

When you detect a fraud attack in progress: Stop all verification sends to limit financial damage. Look at the destination countries, IP addresses, and phone number patterns in your logs. Remove affected countries from your Verify profile’s whitelisted_destinations. Reduce rate limits, add CAPTCHA if not present, and re-enable verifications gradually. Report the incident to Telnyx Support for investigation and potential charge reversal.

Configuration reference

Summary of all Verify profile settings relevant to fraud prevention:

Setting	Endpoint	Purpose
`whitelisted_destinations`	`PATCH /v2/verify_profiles/{id}`	Restrict SMS to specific countries
`code_length`	`PATCH /v2/verify_profiles/{id}`	Set verification code length (4-10)
`default_timeout_secs`	`PATCH /v2/verify_profiles/{id}`	Expiration time for codes

# Example: Production-hardened Verify profile
curl -X PATCH "https://api.telnyx.com/v2/verify_profiles/YOUR_PROFILE_ID" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sms": {
      "whitelisted_destinations": ["US", "CA"],
      "default_timeout_secs": 300,
      "code_length": 6
    },
    "call": {
      "default_timeout_secs": 300
    }
  }'

Next steps

Foundational security concepts for Verify Get started with Telnyx Verify Real-time verification delivery status Brand your verification messages

Number Reputation

Overview

Source: https://developers.telnyx.com/docs/number-reputation/overview.md

Overview

Number Reputation lets you query the spam reputation of your outbound calling phone numbers. For each number you get a reputation snapshot with spam risk level, granular scores, and a category label when the number is flagged. Number Reputation is a standalone monitoring product. It reports spam reputation and does not change how your calls are placed. It is governed by separate Terms of Service from Branded Calling. Number Reputation is currently supported in the US only. Canadian numbers are not accepted.

How it works

Register your business as an Enterprise — an Enterprise can serve Number Reputation, Branded Calling, or both.
Accept the Number Reputation Terms of Service — a one-time step per account.
Render, sign, and upload a Letter of Authorization (LOA) to get a loa_document_id — see the LOA guide.
Enable Number Reputation with that loa_document_id (billable) — your details are submitted for automated vetting (takes minutes).
Wait for both approval gates — reputation status and loa_status must each be approved.
Associate phone numbers for monitoring (up to 100 per request, US numbers, E.164) — billable.
Query reputation scores — cached results are free, fresh (live) queries are billed.
Automatic monitoring re-checks your numbers on a configurable schedule.
Remediate flagged numbers — submit numbers for re-evaluation when spam risk is elevated.

Resource hierarchy

Enterprise (your organization, registered once — shared with Branded Calling)
├── Number Reputation Settings (per-enterprise monitoring configuration)
│   ├── LOA Document (Letter of Authorization)
│   ├── Auto-refresh Schedule (business_daily, daily, weekly, biweekly, monthly, never)
│   └── Reputation Phone Numbers
│       └── Phone Number (+1NPANXXXXXX)
│           └── Reputation Data (spam_risk, scores, spam_category, last_refreshed_at)
├── Remediation Requests (batch re-evaluation of flagged numbers)
│   └── Remediation Phone Numbers (up to 2,000 per request)
└── Terms of Service Agreement (Number Reputation)

An Enterprise can serve Number Reputation, Branded Calling, or both — you don’t need to create a separate Enterprise for each product.
Number Reputation Settings are per-enterprise: one LOA, one auto-refresh schedule, one activation lifecycle.
Each Phone Number gets its own reputation data with spam risk levels and granular scores.
Remediation Requests are batch submissions of flagged numbers for re-evaluation.

Key concepts

Term	Description
Enterprise	Your top-level business registration. Shared with Branded Calling. Required before enabling reputation monitoring.
Letter of Authorization (LOA)	A signed document authorizing Telnyx to manage your numbers’ reputation with call-analytics networks.
Reputation data	Per-number snapshot: `spam_risk`, `spam_category`, four granular scores, and `last_refreshed_at`.
Auto-refresh	Scheduled re-checking of your numbers’ reputation data. Configurable frequency.
Remediation	A request to call-analytics networks to re-evaluate a flagged number’s classification.
Terms of Service	Separate from Branded Calling. Must be accepted before enabling monitoring.

Reputation data

Each registered number returns a reputation_data object with the following fields:

Field	Values	Meaning
`spam_risk`	`low` / `medium` / `high` / `null`	Overall spam-risk classification from the call-analytics networks used by US carriers.
`maturity_score`	0-100 or `null`	How established the number is — based on call volume history over time. Available immediately after registration.
`connection_score`	0-100 or `null`	Whether recipients choose to answer calls from this number.
`engagement_score`	0-100 or `null`	Whether recipients stay on the call after answering.
`sentiment_score`	0-100 or `null`	Whether recipients complain about or block calls from this number.
`spam_category`	string or `null`	Category label assigned by the reputation feed when the number is flagged. Treat as an opaque string — the set may grow over time. `null` means the number is not flagged.
`last_refreshed_at`	ISO 8601 timestamp or `null`	When the reputation data was last updated. `null` if no check has been performed yet.

maturity_score is available immediately after registration because it uses pre-existing call traffic data. The other three scores start as null and populate after the number has sufficient call volume (minimum 4 hours, longer for low-volume numbers). Scores are updated hourly. Known spam_category values include: Telemarketer, Survey, Debt Collector, Nonprofit, Political, and others. The set is not exhaustive and may grow over time.

Constraints

Constraint	Limit
Phone number format	E.164 (`+1NPANXXXXXX`), US numbers only
Numbers per request	100 (atomic — all-or-nothing)
Score range	0-100 (`null` = insufficient data)
Account access	Verified and enterprise-level accounts only
Approval gates	Both reputation `status` and `loa_status` must be `approved` before numbers can be added
Terms of Service	Must be accepted before enabling (separate from Branded Calling ToS)

Ecosystem

Reputation data is sourced from the major call-analytics networks used by US carriers. When you register numbers, Telnyx registers them across that reputation feed on your behalf. You interact only with the Telnyx API.

Next steps

Quickstart guide — get from zero to your first reputation query
Pricing — Number Reputation pricing details
Letter of Authorization — render, sign, upload, and replace a rejected LOA
Reputation Settings — vetting lifecycle, auto-refresh schedules, and configuration
Phone Number Reputation — reputation data model, scores, and querying in depth
Reputation Remediation — submit flagged numbers for re-evaluation

Quickstart

Source: https://developers.telnyx.com/docs/number-reputation/quickstart.md

This guide walks you through enabling Number Reputation and querying your first spam score. You’ll need a verified or enterprise-level Telnyx account and an API key. There are two separate approval gates you must clear before you can add phone numbers — don’t confuse them:

Reputation status must be approved — the activation lifecycle for the enterprise.
loa_status must be approved — Telnyx reviews your signed Letter of Authorization.

Both are tracked independently, and both must read approved before POST .../reputation/numbers will accept numbers.

Prerequisites

A Telnyx account with verified or enterprise level access
An API key
At least one US phone number on your account, in E.164 format
A signed Letter of Authorization (LOA) — you render this from Telnyx in Step 3

Step 1: Accept the Number Reputation Terms of Service

Read the full terms at telnyx.com/terms/reputation-services.

curl -X POST https://api.telnyx.com/v2/terms_of_service/number_reputation/agree \
  -H "Authorization: Bearer YOUR_API_KEY"

This is a one-time step per account. If you skip it, Step 5 (enable) returns 403. To check whether you’ve already agreed, call GET /v2/terms_of_service/status?product_type=number_reputation. That endpoint defaults to branded_calling, so you must pass product_type=number_reputation to read the Number Reputation status.

Step 2: Create an enterprise

If you don’t already have an enterprise, create one. An Enterprise can serve Number Reputation, Branded Calling, or both — you don’t need a separate one. See the Enterprises overview for the full field reference.

curl -X POST https://api.telnyx.com/v2/enterprises \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "legal_name": "Acme Plumbing LLC",
    "doing_business_as": "Acme Plumbing",
    "organization_type": "commercial",
    "organization_legal_type": "llc",
    "country_code": "US",
    "jurisdiction_of_incorporation": "Delaware",
    "website": "https://acmeplumbing.example.com",
    "fein": "12-3456789",
    "industry": "technology",
    "number_of_employees": "51-200",
    "organization_contact": {
      "first_name": "Sam",
      "last_name": "Owner",
      "email": "sam@acmeplumbing.example.com",
      "job_title": "Compliance Lead",
      "phone_number": "+13125550000"
    },
    "billing_contact": {
      "first_name": "Alex",
      "last_name": "Bill",
      "email": "billing@acmeplumbing.example.com",
      "phone_number": "+13125550001"
    },
    "organization_physical_address": {
      "country": "US",
      "administrative_area": "IL",
      "city": "Chicago",
      "postal_code": "60601",
      "street_address": "100 Main St"
    },
    "billing_address": {
      "country": "US",
      "administrative_area": "IL",
      "city": "Chicago",
      "postal_code": "60601",
      "street_address": "100 Main St"
    }
  }'

Save the id from the response — this is your enterprise_id.

Step 3: Render the Letter of Authorization (LOA)

Telnyx renders a pre-filled LOA PDF from your enterprise record. You do not upload your own template — you render the Telnyx one, sign it, and upload the signed copy back.

curl -X POST https://api.telnyx.com/v2/enterprises/{enterprise_id}/reputation/loa \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -o loa.pdf \
  -d '{}'

The response body is the PDF itself (application/pdf); -o loa.pdf saves it to disk. Rendering the LOA is not billable. See the LOA guide for the optional agent (reseller) and signature body fields, and the full approval/replacement flow.

Step 4: Sign the LOA and upload it to the Documents API

Sign loa.pdf (e-signature or wet signature), then upload the signed copy to the Telnyx Documents API:

curl -X POST https://api.telnyx.com/v2/documents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@loa.pdf"

The response contains the document id:

{
  "data": {
    "id": "2a7e8337-e803-4057-a4ae-26c40eb0bc6c"
  }
}

Save data.id — you’ll pass it as loa_document_id in the next step.

Step 5: Enable Number Reputation

curl -X POST https://api.telnyx.com/v2/enterprises/{enterprise_id}/reputation \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "loa_document_id": "2a7e8337-e803-4057-a4ae-26c40eb0bc6c",
    "check_frequency": "business_daily"
  }'

check_frequency is optional and defaults to business_daily. Enabling reputation is a billable action. See Number Reputation pricing for current pricing.

Step 6: Wait for both approval gates

Your enterprise details are submitted for automated vetting and Telnyx reviews your signed LOA. Poll the reputation settings until both status and loa_status read approved:

curl https://api.telnyx.com/v2/enterprises/{enterprise_id}/reputation \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "data": {
    "status": "approved",
    "loa_status": "approved"
  }
}

Field	Gate
`status`	Activation lifecycle: `pending` → `approved` (or `rejected` — see `rejection_reasons`).
`loa_status`	LOA review: `pending` → `approved` (or `rejected` — replace the LOA, see the LOA guide).

You cannot add numbers until both are approved.

Step 7: Associate phone numbers

Once both gates are approved, add phone numbers for monitoring:

curl -X POST https://api.telnyx.com/v2/enterprises/{enterprise_id}/reputation/numbers \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_numbers": ["+12025551234", "+12025555678"]
  }'

Up to 100 numbers per request. This is an atomic operation — all numbers succeed or all fail. Numbers must be US numbers in E.164 format (+1NPANXXXXXX), in-service, and belong to your Telnyx phone-number inventory. Non-US numbers are rejected. Adding numbers is a billable action. See Number Reputation pricing for current pricing. A freshly added number has reputation_data: null until Telnyx collects its first refresh. Querying it (Step 8) triggers an immediate lookup. Because the number has no cached data yet, that first query performs a live (billed) lookup even from the “Cached” endpoint; cached reads are free only once data exists.

Step 8: Query reputation

URL-encode the leading + of the phone number in the path as %2B.

Cached (free, once data exists)

The first query on a number with no cached reputation data triggers a live, billed lookup regardless of this endpoint; only subsequent reads are free.

curl https://api.telnyx.com/v2/enterprises/{enterprise_id}/reputation/numbers/%2B12025551234 \
  -H "Authorization: Bearer YOUR_API_KEY"

Fresh — live query (billed)

curl "https://api.telnyx.com/v2/enterprises/{enterprise_id}/reputation/numbers/%2B12025551234?fresh=true" \
  -H "Authorization: Bearer YOUR_API_KEY"

The response includes:

{
  "data": {
    "id": "8a4b1f5e-2f12-4c0c-9a98-9b3a7d8b8e62",
    "enterprise_id": "4a6192a4-573d-446d-b3ce-aff9117272a6",
    "phone_number": "+12025551234",
    "reputation_data": {
      "spam_risk": "low",
      "spam_category": null,
      "maturity_score": 82,
      "connection_score": 75,
      "engagement_score": 68,
      "sentiment_score": 90,
      "last_refreshed_at": "2026-04-26T18:09:24.785211Z"
    },
    "created_at": "2026-04-26T18:06:51.940749Z",
    "updated_at": "2026-04-26T18:09:24.785211Z"
  }
}

Every field in reputation_data is nullable, and the whole object is null until the first refresh has been collected.

Step 9: Manage ongoing monitoring

Change auto-refresh frequency

curl -X PATCH https://api.telnyx.com/v2/enterprises/{enterprise_id}/reputation/frequency \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"check_frequency": "daily"}'

The enterprise’s reputation status must be approved; a request made while it is still pending returns 400 Bad Request.

Remove a number from monitoring

curl -X DELETE https://api.telnyx.com/v2/enterprises/{enterprise_id}/reputation/numbers/%2B12025551234 \
  -H "Authorization: Bearer YOUR_API_KEY"

Disable Number Reputation entirely

curl -X DELETE https://api.telnyx.com/v2/enterprises/{enterprise_id}/reputation \
  -H "Authorization: Bearer YOUR_API_KEY"

Simplified endpoints

If your account has only one enterprise, you can use simplified endpoints without the enterprise_id:

# List all monitored numbers
curl https://api.telnyx.com/v2/reputation/numbers \
  -H "Authorization: Bearer YOUR_API_KEY"

# Get reputation for a specific number
curl https://api.telnyx.com/v2/reputation/numbers/%2B12025551234 \
  -H "Authorization: Bearer YOUR_API_KEY"

# Remove a number from monitoring (URL-encode the leading + as %2B in the path)
curl -X DELETE https://api.telnyx.com/v2/reputation/numbers/%2B12025551234 \
  -H "Authorization: Bearer YOUR_API_KEY"

Portal setup

You can also set up Number Reputation from the Telnyx Portal — the full workflow (accept ToS, create enterprise, render LOA, enable monitoring, add numbers, query scores) is available in the UI. The API and Portal are fully interchangeable.

Next steps

Learn about Reputation Settings — vetting lifecycle, auto-refresh schedules, and configuration
Read the LOA guide — render, sign, upload, and replace a rejected LOA
Explore Phone Number Reputation — reputation data model, scores, and querying in depth
Submit flagged numbers for Reputation Remediation

Pricing

Source: https://developers.telnyx.com/docs/number-reputation/pricing.md

Pricing

Number Reputation pricing has three components:

Component	Cost	Description
Reputation monitoring	$100/month per Enterprise	Recurring monthly fee to enable reputation monitoring on an enterprise.
Reputation check	$0.10 per check	Charged per reputation query. Cached reads are free; fresh (live) queries and auto-refreshes are billed.
Remediation check	$1.00 per check	Charged per number submitted for reputation remediation (re-evaluation).

Rendering the LOA is not billable. You only pay once you enable reputation monitoring and add numbers. For the full pricing details, see the Telnyx Numbers pricing page.

How billing works

Action	Billed?
Render LOA PDF	No
Enable reputation monitoring	Yes ($100 MRC)
Add phone numbers	Yes ($0.10 per number per check)
Cached reputation query	No (free once data exists)
Fresh reputation query (`?fresh=true`)	Yes ($0.10 per check)
Forced refresh	Yes ($0.10 per check)
Auto-refresh (scheduled)	Yes ($0.10 per check per number)
Submit remediation request	Yes ($1.00 per number)

Enterprise registration is free. An Enterprise can serve Number Reputation, Branded Calling, or both.

Letter of Authorization

Source: https://developers.telnyx.com/docs/number-reputation/loa.md

Overview

Before Telnyx can register your phone numbers with the major call-analytics networks used by US carriers, you must provide a signed Letter of Authorization (LOA). The LOA authorizes Telnyx to manage your numbers’ reputation on your behalf. The LOA is the #1 thing customers get stuck on, so follow these steps in order. There are two separate approval gates you must clear before you can add phone numbers:

Reputation status must be approved (the activation lifecycle).
loa_status must be approved (Telnyx reviews the signed LOA).

Both must be approved. They are tracked independently. Telnyx renders a pre-filled LOA from your enterprise record. The enterprise identity, address, and authorized-representative contact are read from the enterprise you created — you do not pass them again here.

curl -X POST https://api.telnyx.com/v2/enterprises/{enterprise_id}/reputation/loa \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -o loa.pdf \
  -d '{}'

The response body is the PDF itself (application/pdf). The -o loa.pdf flag saves it to disk. Rendering the LOA is not billable. You only pay once you enable reputation and add numbers. Optional body fields (both optional):

Field	Description
`agent`	A third-party reseller / partner block, used only when a partner manages the enterprise’s numbers. Omit when the enterprise works directly with Telnyx.
`signature`	Embeds a signature image in the rendered PDF. When omitted, the PDF is returned unsigned for you to sign manually.

To render with the agent (reseller) block:

curl -X POST https://api.telnyx.com/v2/enterprises/{enterprise_id}/reputation/loa \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -o loa.pdf \
  -d '{
    "agent": {
      "legal_name": "Reseller LLC",
      "dba": "Reseller",
      "street_address": "500 Market St",
      "extended_address": "Suite 200",
      "city": "San Francisco",
      "administrative_area": "CA",
      "postal_code": "94105",
      "country": "US",
      "contact_name": "Pat Partner",
      "contact_title": "Account Manager",
      "contact_email": "pat@reseller.com",
      "contact_phone": "+13125550000"
    }
  }'

To embed a signature at render time instead of signing the PDF by hand:

curl -X POST https://api.telnyx.com/v2/enterprises/{enterprise_id}/reputation/loa \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -o loa.pdf \
  -d '{
    "signature": {
      "image_base64": "BASE64_ENCODED_SIGNATURE_IMAGE",
      "signer_name": "Jane Smith"
    }
  }'

If you did not embed a signature at render time, open loa.pdf and sign it (e-signature or wet signature). Save the signed copy. Upload the signed PDF to the Telnyx Documents API. The Documents API returns a document id — that value is your loa_document_id.

curl -X POST https://api.telnyx.com/v2/documents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@loa.pdf"

The response contains the document id:

{
  "data": {
    "id": "2a7e8337-e803-4057-a4ae-26c40eb0bc6c"
  }
}

Save data.id — you’ll pass it as loa_document_id in the next step. Enable Number Reputation, passing the document id and a refresh frequency.

curl -X POST https://api.telnyx.com/v2/enterprises/{enterprise_id}/reputation \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "loa_document_id": "2a7e8337-e803-4057-a4ae-26c40eb0bc6c",
    "check_frequency": "business_daily"
  }'

Enabling reputation is a billable action. See Number Reputation pricing for current pricing. Telnyx reviews your uploaded LOA. Track loa_status on the reputation settings:

curl https://api.telnyx.com/v2/enterprises/{enterprise_id}/reputation \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "data": {
    "status": "approved",
    "loa_status": "pending"
  }
}

loa_status moves pending → approved (or rejected). You cannot add phone numbers until loa_status is approved and reputation status is approved.

LOA approval gate

`loa_status`	Meaning
`pending`	Telnyx is reviewing the uploaded LOA. Numbers cannot be added yet.
`approved`	LOA accepted. Combined with reputation `status` = `approved`, you can add numbers.
`rejected`	LOA was not accepted. Replace it (see below) to retry.

Reputation status and loa_status are two separate gates. Both must read approved before POST .../reputation/numbers will accept numbers.

Replace a pending or rejected LOA

If your LOA is rejected — or it is still pending and you need to upload a corrected document — render a fresh PDF, sign and upload it to the Documents API to get a new loa_document_id, then point your reputation settings at it:

curl -X PATCH https://api.telnyx.com/v2/enterprises/{enterprise_id}/reputation/loa \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "loa_document_id": "NEW_DOCUMENT_ID"
  }'

Replacing the LOA resets loa_status back to pending. The new document must be approved again before more numbers can be added. This is the recovery path for a rejected LOA. You can only replace the LOA while loa_status is pending or rejected. Once loa_status is approved, the document is locked in and this PATCH returns 400 Bad Request (“The authorization document cannot be changed after it has been approved.”). To start over with a different LOA after approval, disable Number Reputation and re-enable it with the new document.

Next steps

Enable and configure reputation
Associate phone numbers once both gates are approved

Reputation Settings

Source: https://developers.telnyx.com/docs/number-reputation/settings.md

Overview

Number Reputation Settings control the monitoring lifecycle for your enterprise. You enable reputation monitoring, configure how often numbers are checked, and manage the vetting status.

Prerequisites

Before enabling Number Reputation, you need:

An Enterprise registered on your account — an Enterprise can serve Number Reputation, Branded Calling, or both.
A signed Letter of Authorization (LOA) rendered, signed, and uploaded to the Documents API to obtain a loa_document_id — follow the LOA guide. The LOA authorizes Telnyx to register your numbers with the major call-analytics networks used by US carriers.
Agreement to the Number Reputation Terms of Service.

Enable Number Reputation

Submit your LOA document ID to enable reputation monitoring:

curl -X POST https://api.telnyx.com/v2/enterprises/{enterprise_id}/reputation \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "loa_document_id": "2a7e8337-e803-4057-a4ae-26c40eb0bc6c",
    "check_frequency": "business_daily"
  }'

check_frequency is optional and defaults to business_daily. Your enterprise details are submitted for automated vetting. This typically takes minutes. Enabling reputation is a billable action. See Number Reputation pricing for current pricing. Enabling returns 403 if you have not agreed to the Number Reputation Terms of Service. See Terms of Service below.

Two approval gates

Two statuses must each read approved before you can add phone numbers — they are tracked independently:

Status	Meaning
`status`	Activation lifecycle of the enterprise’s reputation. `pending` → `approved` / `rejected`.
`loa_status`	Telnyx’s review of the signed LOA. `pending` → `approved` / `rejected`.

status and loa_status are two separate gates. Both must be approved before POST .../reputation/numbers will accept numbers. A rejected loa_status is recoverable — replace the LOA per the LOA guide.

Vetting lifecycle

pending ──► approved    (activation approved)
pending ──► rejected    (check rejection_reasons in the response)
approved ──► (removed)   (reputation disabled via DELETE)

Once you disable reputation, the settings are removed: a subsequent GET .../reputation returns 404 Not Found rather than a readable status. Check your current status:

curl https://api.telnyx.com/v2/enterprises/{enterprise_id}/reputation \
  -H "Authorization: Bearer YOUR_API_KEY"

The response includes:

Field	Description
`status`	Activation lifecycle: `pending`, `approved`, or `rejected`. (After you disable reputation the settings are removed and `GET` returns `404` instead of a status.)
`loa_status`	LOA review gate: `pending`, `approved`, or `rejected`.
`check_frequency`	Current auto-refresh schedule.
`loa_document_id`	Your uploaded LOA reference (nullable).
`rejection_reasons`	Array of reasons, populated when `status` is `rejected` (otherwise `null`).
`created_at` / `updated_at`	Timestamps.

Auto-refresh schedules

Telnyx automatically runs fresh reputation queries on all your registered numbers based on the configured check_frequency:

Frequency	Schedule
`business_daily`	Mon-Fri (default)
`daily`	Every day including weekends
`weekly`	Once per week
`biweekly`	Every 2 weeks
`monthly`	Once per month
`never`	Manual only — use `?fresh=true` or a forced refresh

Change the schedule

curl -X PATCH https://api.telnyx.com/v2/enterprises/{enterprise_id}/reputation/frequency \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"check_frequency": "daily"}'

The enterprise’s reputation status must be approved. A frequency change requested while status is still pending is rejected with 400 Bad Request. Choose a frequency that balances data freshness with cost. Each auto-refresh counts as a billed query per number — see Number Reputation pricing.

Disable Number Reputation

To stop monitoring entirely and remove the enterprise from reputation tracking:

curl -X DELETE https://api.telnyx.com/v2/enterprises/{enterprise_id}/reputation \
  -H "Authorization: Bearer YOUR_API_KEY"

This de-registers your numbers from the reputation feed and removes the reputation settings. A subsequent GET .../reputation returns 404 Not Found; to monitor again you must re-enable with a fresh LOA.

Terms of Service

You must accept the Number Reputation Terms of Service (read the full terms) before enabling monitoring:

curl -X POST https://api.telnyx.com/v2/terms_of_service/number_reputation/agree \
  -H "Authorization: Bearer YOUR_API_KEY"

This is a one-time step per account. To check ToS status, call GET /v2/terms_of_service/status?product_type=number_reputation. This endpoint defaults to branded_calling, so you must pass product_type=number_reputation. Likewise, GET /v2/terms_of_service/agreements also defaults to branded_calling — pass ?product_type=number_reputation to scope the list to Number Reputation.

Phone Numbers

Source: https://developers.telnyx.com/docs/number-reputation/phone-numbers.md

Overview

Once your enterprise is approved for Number Reputation — both reputation status and loa_status read approved — you can associate phone numbers for monitoring. Each number gets its own reputation data with spam risk levels and granular scores. Both approval gates must be approved before numbers are accepted. If you haven’t cleared them yet, start with the LOA guide and Reputation Settings.

Associate phone numbers

Add phone numbers for reputation monitoring:

curl -X POST https://api.telnyx.com/v2/enterprises/{enterprise_id}/reputation/numbers \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_numbers": ["+12025551234", "+12025555678"]
  }'

Up to 100 numbers per request
Atomic operation — all numbers succeed or all fail
Numbers must be US numbers in E.164 format (+1NPANXXXXXX) — non-US numbers are rejected
Numbers must be in-service and belong to your Telnyx phone-number inventory Adding numbers is a billable action. See Number Reputation pricing for current pricing. In the request body, phone numbers are JSON string values, so the leading + is written literally ("+12025551234"). In path parameters (the get/delete-by-number endpoints below) URL-encode the + as %2B.

A freshly added number has reputation_data: null until Telnyx collects its first refresh. Query it (below) to trigger an immediate lookup.

Query reputation

URL-encode the leading + of the phone number in the path as %2B — e.g. +12025551234 becomes %2B12025551234.

Cached query (free)

Returns the most recent stored reputation data:

curl https://api.telnyx.com/v2/enterprises/{enterprise_id}/reputation/numbers/%2B12025551234 \
  -H "Authorization: Bearer YOUR_API_KEY"

Fresh query (billed)

Fetches live data from the reputation feed:

curl "https://api.telnyx.com/v2/enterprises/{enterprise_id}/reputation/numbers/%2B12025551234?fresh=true" \
  -H "Authorization: Bearer YOUR_API_KEY"

If no cached data exists for a number, a fresh query is automatically triggered regardless of the fresh parameter — so a brand-new number always returns live data on its first GET (and counts as a billed query). If the analytics networks don’t have data for the number yet, reputation_data will still be null. Live (fresh) queries are billable. See Number Reputation pricing for current pricing.

Reputation data model

Each number returns a reputation_data object. The object is null until the first refresh has been collected, and every field inside it is nullable:

{
  "data": {
    "id": "16286ab3-038a-4a5c-9792-309026cf6b9e",
    "phone_number": "+12025551234",
    "enterprise_id": "4a6192a4-573d-446d-b3ce-aff9117272a6",
    "reputation_data": {
      "spam_risk": "low",
      "spam_category": null,
      "maturity_score": 82,
      "connection_score": 75,
      "engagement_score": 68,
      "sentiment_score": 90,
      "last_refreshed_at": "2026-03-24T12:00:00Z"
    },
    "created_at": "2026-04-26T18:06:51.940749Z",
    "updated_at": "2026-04-26T18:09:24.785211Z"
  }
}

Spam risk

Value	Meaning
`low`	Number has a clean reputation
`medium`	Some risk indicators present — the number may have been labeled as spam in the recent past
`high`	Number is likely flagged as spam by carriers
`null`	Not enough data yet

Granular scores (0-100)

Score	What it measures
`maturity_score`	How established the number is — based on call volume history over time. Available immediately after registration.
`connection_score`	Whether recipients choose to answer calls from this number.
`engagement_score`	Whether recipients stay on the call after answering.
`sentiment_score`	Whether recipients complain about or block calls from this number.

A null score means there isn’t enough data to make a determination. maturity_score is available immediately after registration because it uses pre-existing call traffic data. The other three scores start as null and populate after the number has sufficient call volume (minimum 4 hours, longer for low-volume numbers). Scores are updated hourly.

Spam categories

If a number is flagged, spam_category is the category label assigned to it by the reputation feed. Known values include:

Category	Description
`Telemarketer`	Number is flagged as a telemarketing caller
`Survey`	Number is flagged as a survey/polling caller
`Debt Collector`	Number is flagged as a debt collection caller
`Nonprofit`	Number is flagged as a nonprofit/fundraising caller
`Political`	Number is flagged as a political campaign caller

Treat the field as an opaque string — the set may grow over time. It is null when the number is not flagged.

List all monitored numbers

curl "https://api.telnyx.com/v2/enterprises/{enterprise_id}/reputation/numbers" \
  -H "Authorization: Bearer YOUR_API_KEY"

Supports pagination with page[number] and page[size] query parameters. Page numbering is 1-based; for this enterprise-scoped endpoint page[size] defaults to 10 and is capped at 250. You can also filter by phone number with filter[phone_number][contains] (partial match) or filter[phone_number][eq] (exact match).

curl -g "https://api.telnyx.com/v2/enterprises/{enterprise_id}/reputation/numbers?page[number]=1&page[size]=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

The simplified list endpoint (/v2/reputation/numbers) defaults to a page[size] of 20, while this enterprise-scoped endpoint defaults to 10. Pass page[size] explicitly if you depend on a specific page size.

Force a refresh

Refresh the stored reputation data for specific numbers immediately, in addition to the scheduled check_frequency:

curl -X POST https://api.telnyx.com/v2/enterprises/{enterprise_id}/reputation/numbers/refresh \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_numbers": ["+12025551234"]
  }'

Up to 100 numbers per call. The response reports the per-number outcome:

{
  "data": {
    "results": [
      { "phone_number": "+12025551234", "success": true, "error": null }
    ],
    "total_requested": 1,
    "total_successful": 1,
    "total_failed": 0
  }
}

Forcing a refresh performs live reputation lookups, which are billable. See Number Reputation pricing for current pricing. Refreshes are subject to per-enterprise rate limits.

Remove a number from monitoring

curl -X DELETE https://api.telnyx.com/v2/enterprises/{enterprise_id}/reputation/numbers/%2B12025551234 \
  -H "Authorization: Bearer YOUR_API_KEY"

Simplified endpoints

If your account has only one enterprise, you can skip the enterprise_id path parameter:

Method	Simplified path
GET	`/v2/reputation/numbers`
GET	`/v2/reputation/numbers/{phone_number}`
DELETE	`/v2/reputation/numbers/{phone_number}`

Remember to URL-encode the + as %2B in the {phone_number} path:

# List all monitored numbers (simplified)
curl https://api.telnyx.com/v2/reputation/numbers \
  -H "Authorization: Bearer YOUR_API_KEY"

# Get reputation for a specific number (simplified)
curl https://api.telnyx.com/v2/reputation/numbers/%2B12025551234 \
  -H "Authorization: Bearer YOUR_API_KEY"

# Remove a specific number (simplified)
curl -X DELETE https://api.telnyx.com/v2/reputation/numbers/%2B12025551234 \
  -H "Authorization: Bearer YOUR_API_KEY"

Remediation

Source: https://developers.telnyx.com/docs/number-reputation/remediation.md

Overview

When one of your monitored numbers is flagged with an elevated spam_risk, you can submit it for reputation remediation — a request to the call-analytics networks to re-evaluate the number’s classification. You submit a batch of numbers, Telnyx forwards the request on your behalf, and you poll the request to track its status and per-number outcome. Remediation is asynchronous. The submit call returns 202 Accepted with a request id; the request then moves through processing states until it completes. Use the GET endpoints to poll status and per-number results. Submitting a remediation request does not guarantee a number will be removed from any spam or block list. Remediation is a re-evaluation request to the call-analytics networks — the outcome may be that the number remains flagged (requires_review or refused). Even after a number is successfully remediated, calls from it can still be blocked or labeled by downstream spam filters and carriers. Those systems are outside Telnyx’s control, and a successful remediation does not override them. Both Number Reputation approval gates must be cleared (reputation status and loa_status both approved) and the Number Reputation Terms of Service accepted before you can submit remediation requests. See the LOA guide and Reputation Settings.

Submit numbers for remediation

curl -X POST https://api.telnyx.com/v2/enterprises/{enterprise_id}/reputation/remediation \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_numbers": ["+12025551234", "+12025555678"],
    "call_purpose": "Outbound appointment reminders for our dental clinic.",
    "contact_email": "ops@example.com",
    "webhook_url": "https://example.com/hooks/remediation"
  }'

Field	Required	Description
`phone_numbers`	yes	Phone numbers in E.164 format. 1 to 2,000 per request. Must belong to this enterprise.
`call_purpose`	yes	Free-text description of how the numbers are used (1 to 2,000 chars).
`contact_email`	no	A contact email for this remediation request, used for tracking and any follow-up (max 255 chars).
`webhook_url`	no	Optional `https://` URL to receive status notifications (max 2,048 chars).

The endpoint returns 202 Accepted with the persisted request and its initial status of pending:

{
  "data": {
    "id": "9f1c8a2e-5b3d-4e7a-9c11-2a6f0d3b4c55",
    "status": "pending",
    "phone_numbers_count": 2,
    "phone_numbers_submitted": 2,
    "phone_numbers_ineligible": 0,
    "call_purpose": "Outbound appointment reminders for our dental clinic.",
    "contact_email": "ops@example.com",
    "webhook_url": "https://example.com/hooks/remediation",
    "created_at": "2026-06-07T18:06:51.940749Z",
    "updated_at": "2026-06-07T18:06:51.940749Z",
    "tier1_completed_at": null,
    "tier2_completed_at": null,
    "results": null
  }
}

A number that already has an in-flight remediation request cannot be submitted again — the request returns 409 Conflict. Numbers that do not belong to this enterprise return 422 Unprocessable Entity.

Count fields

Field	Meaning
`phone_numbers_count`	Total numbers in the batch, including any later cancelled. May exceed the sum of the per-category result buckets.
`phone_numbers_submitted`	Numbers accepted for remediation (not rejected as ineligible). Counts numbers still queued as well as processed ones.
`phone_numbers_ineligible`	Numbers rejected before submission (for example, in a cooldown window).

Get a remediation request

Retrieve full detail for one request, including per-number results once they are available:

curl https://api.telnyx.com/v2/enterprises/{enterprise_id}/reputation/remediation/9f1c8a2e-5b3d-4e7a-9c11-2a6f0d3b4c55 \
  -H "Authorization: Bearer YOUR_API_KEY"

A completed request includes the populated results object:

{
  "data": {
    "id": "9f1c8a2e-5b3d-4e7a-9c11-2a6f0d3b4c55",
    "status": "completed",
    "phone_numbers_count": 2,
    "phone_numbers_submitted": 2,
    "phone_numbers_ineligible": 0,
    "call_purpose": "Outbound appointment reminders for our dental clinic.",
    "contact_email": "ops@example.com",
    "webhook_url": "https://example.com/hooks/remediation",
    "created_at": "2026-06-07T18:06:51.940749Z",
    "updated_at": "2026-06-07T19:42:10.112233Z",
    "tier1_completed_at": "2026-06-07T19:10:04.000000Z",
    "tier2_completed_at": "2026-06-07T19:42:10.000000Z",
    "results": {
      "remediated": ["+12025551234"],
      "not_flagged": [],
      "requires_review": ["+12025555678"],
      "ineligible": [],
      "refused": []
    }
  }
}

A request that is not found — or does not belong to this enterprise — returns 404 Not Found.

Status values

status is the customer-facing meta-status:

`status`	Meaning
`pending`	Request accepted and queued; not yet forwarded for review.
`in_progress`	Forwarded and under review by the call-analytics networks.
`completed`	Review finished. Inspect `results` for the per-number outcome.
`failed`	The request could not be processed.
`cancelled`	The request was cancelled.

results is null while the request is still pending and is populated once results are available.

Per-number result buckets

When results is populated, each number falls into exactly one bucket. Empty buckets are returned as empty arrays (never omitted), so you can iterate without null-checking each key:

Bucket	Meaning
`remediated`	The number’s classification was successfully re-evaluated and cleared.
`not_flagged`	The number was not flagged, so no remediation was needed.
`requires_review`	The number needs further review and remains flagged for now.
`ineligible`	The number was rejected before submission (for example, in a cooldown window).
`refused`	The re-evaluation request was declined; the number remains flagged.

A number landing in the remediated bucket means the analytics networks re-evaluated and cleared it — it does not guarantee the number is removed from every spam list, and downstream carriers and spam filters may still block or label calls from it.

List remediation requests

curl -g "https://api.telnyx.com/v2/enterprises/{enterprise_id}/reputation/remediation?page[number]=1&page[size]=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

List items are a slim shape — they omit results, webhook_url, and the count breakdown. Call get by id for full detail.

{
  "data": [
    {
      "id": "9f1c8a2e-5b3d-4e7a-9c11-2a6f0d3b4c55",
      "status": "completed",
      "phone_numbers_count": 2,
      "call_purpose": "Outbound appointment reminders for our dental clinic.",
      "created_at": "2026-06-07T18:06:51.940749Z",
      "updated_at": "2026-06-07T19:42:10.112233Z",
      "tier1_completed_at": "2026-06-07T19:10:04.000000Z",
      "tier2_completed_at": "2026-06-07T19:42:10.000000Z"
    }
  ],
  "meta": {
    "page_number": 1,
    "page_size": 20,
    "total_results": 1,
    "total_pages": 1
  }
}

Pagination

Pagination is JSON:API. Page numbering is 1-based; page[size] defaults to 20 and is capped at 250.

curl -g "https://api.telnyx.com/v2/enterprises/{enterprise_id}/reputation/remediation?page[number]=2&page[size]=50" \
  -H "Authorization: Bearer YOUR_API_KEY"

Filters

Filter	Description
`filter[status]`	Filter by customer-facing status: `pending`, `in_progress`, `completed`, `failed`, or `cancelled`.
`filter[created_at][gte]`	Created on or after this ISO 8601 timestamp.
`filter[created_at][lte]`	Created on or before this ISO 8601 timestamp.

curl -g "https://api.telnyx.com/v2/enterprises/{enterprise_id}/reputation/remediation?filter[status]=completed&filter[created_at][gte]=2026-06-01T00:00:00Z" \
  -H "Authorization: Bearer YOUR_API_KEY"

Webhooks

When you provide a webhook_url in the remediation request, Telnyx sends status notifications to that URL as the request progresses. The webhook events are:

Event	Description
`number_reputation.remediation.tier1_complete`	First-tier review complete. The request continues to tier 2.
`number_reputation.remediation.completed`	Remediation finished. Inspect `results` for the per-number outcome.
`number_reputation.remediation.failed`	The request could not be processed.

Webhook payloads include the remediation request id, status, and results (when populated). Ensure your webhook endpoint is publicly accessible and responds with 200 to acknowledge receipt.

Next steps

Query reputation scores to see which numbers are flagged.
Reputation Settings to manage auto-refresh schedules and the activation lifecycle.
Number Reputation pricing for remediation pricing details.

API Reference (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

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.
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.
Retrieve all comments
Create a comment
Retrieve a comment
Mark a comment as read

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

Advanced Number Orders

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
Retrieves a phone number blocks job
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
Retrieve a phone number
Update a phone number
Delete a phone number
Change the bundle status for a phone number (set to being in a bundle or remove from a bundle)
Enable emergency for a phone number
Retrieve a phone number with voice settings
Update a phone number with 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

CSV Downloads

Bulk Phone Number Operations

Lists the phone numbers jobs
Retrieve a phone numbers job
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

Phone Number Porting

Run a portability check: Runs a portability check, returning the results immediately.

Porting Orders

List all porting orders: Returns a list of your porting order.
Create a porting order: Creates a new porting order object.
Retrieve a porting order: Retrieves the details of an existing porting order.
Edit a porting order: Edits the details of an existing porting order.
Delete a porting order: Deletes an existing porting order. This operation is restrict to porting orders in draft state.
Submit a porting order.: Confirm and submit your porting order.
Cancel a porting order: Cancel a porting order
Activate every number in a porting order asynchronously.: Activate each number in a porting order asynchronously. This operation is limited to US FastPort orders only.
Share a porting order: Creates a sharing token for a porting order. The token can be used to share the porting order with non-Telnyx users.
List allowed FOC dates: Returns a list of allowed FOC dates for a porting order.
List all comments of a porting order: Returns a list of all comments of a porting order.
Create a comment for a porting order: Creates a new comment for a porting order.
List all porting phone numbers: Returns a list of your porting phone numbers.
List all associated phone numbers: Returns a list of all associated phone numbers for a porting order. Associated phone numbers are used for partial porting in GB to specify which phone numbers…
Create an associated phone number: Creates a new associated phone number for a porting order. This is used for partial porting in GB to specify which phone numbers should be kept or disconnected.
Delete an associated phone number: Deletes an associated phone number from a porting order.
List all phone number blocks: Returns a list of all phone number blocks of a porting order.
Create a phone number block: Creates a new phone number block.
Delete a phone number block: Deletes a phone number block.
List all phone number extensions: Returns a list of all phone number extensions of a porting order.
Create a phone number extension: Creates a new phone number extension.
Delete a phone number extension: Deletes a phone number extension.
List all phone number configurations: Returns a list of phone number configurations paginated.
Create a list of phone number configurations: Creates a list of phone number configurations.
List LOA configurations: List the LOA configurations.
Create a LOA configuration: Create a LOA configuration.
Retrieve a LOA configuration: Retrieve a specific LOA configuration.
Update a LOA configuration: Update a specific LOA configuration.
Delete a LOA configuration: Delete a specific LOA configuration.
Preview a LOA configuration: Preview a specific LOA configuration.
Preview the LOA configuration parameters: Preview the LOA template that would be generated without need to create LOA configuration.
Download a porting order loa template: Download a porting order loa template
List additional documents: Returns a list of additional documents for a porting order.
Create a list of additional documents: Creates a list of additional documents for a porting order.
Delete an additional document: Deletes an additional document for a porting order.
List porting order requirements: Returns a list of all requirements based on country/number type for this porting order.
List verification codes: Returns a list of verification codes for a porting order.
Send the verification codes: Send the verification code for all porting phone numbers.
Verify the verification code for a list of phone numbers: Verifies the verification code for a list of phone numbers.
List action requirements for a porting order: Returns a list of action requirements for a specific porting order.
Initiate an action requirement: Initiates a specific action requirement for a porting order.
List available carriers in the UK: List available carriers in the UK.
List all porting events: Returns a list of all porting events.
Show a porting event: Show a specific porting event.
Republish a porting event: Republish a specific porting event.
List porting related reports: List the reports generated about porting operations.
Create a porting related report: Generate reports about porting operations.
Retrieve a report: Retrieve a specific report generated.
List all porting activation jobs: Returns a list of your porting activation jobs.
Retrieve a porting activation job: Returns a porting activation job.
Update a porting activation job: Updates the activation time of a porting activation job.
List all exception types: Returns a list of all possible exception types for a porting order.
Retrieve the associated V1 sub_request_id and port_request_id: Retrieve the associated V1 sub_request_id and port_request_id

Number Portout

List portout requests: Returns the portout requests according to filters
Get a portout request: Returns the portout request based on the ID provided
List all comments for a portout request: Returns a list of comments for a portout request.
Create a comment on a portout request: Creates a comment on a portout request.
List supporting documents on a portout request: List every supporting documents for a portout request.
Create a list of supporting documents on a portout request: Creates a list of supporting documents on a portout request.
Update Status: Authorize or reject portout request
List all port-out events: Returns a list of all port-out events.
Show a port-out event: Show a specific port-out event.
Republish a port-out event: Republish a specific port-out event.
List eligible port-out rejection codes for a specific order: Given a port-out ID, list rejection codes that are eligible for that port-out
List port-out related reports: List the reports generated about port-out operations.
Create a port-out related report: Generate reports about port-out operations.
Retrieve a report: Retrieve a specific report generated.

Requirements

List all requirements: List all requirements with filtering, sorting, and pagination
Retrieve a document requirement: Retrieve a document requirement record

Requirement Types

List all requirement types: List all requirement types ordered by created_at descending
Retrieve a requirement types: Retrieve a requirement type by id

Verified Numbers

List all Verified Numbers: Gets a paginated list of Verified Numbers.
Request phone number verification: Initiates phone number verification procedure. Supports DTMF extension dialing for voice calls to numbers behind IVR systems.
Retrieve a verified number
Delete a verified number
Submit verification code

Documents

List all document links: List all documents links ordered by created_at descending.
List all documents: List all documents ordered by created_at descending.
Upload a document: Upload a document.<br /><br />Uploaded files must be linked to a service within 30 minutes or they will be automatically deleted.
Retrieve a document: Retrieve a document.
Update a document: Update a document.
Delete a document: Delete a document.<br /><br />A document can only be deleted if it’s not linked to a service. If it is linked to a service, it must be unlinked prior to deleti…
Download a document: Download a document.
Generate a temporary download link for a document: Generates a temporary pre-signed URL that can be used to download the document directly from the storage backend without authentication.

Bundles

Retrieve Bundles: Get all allowed bundles.
Get Bundle By Id: Get a single bundle by ID.

User Bundles

Get User Bundles: Get a paginated list of user bundles.
Create User Bundles: Creates multiple user bundles for the user.
Get Unused User Bundles: Returns all user bundles that aren’t in use.
Get User Bundle by Id: Retrieves a user bundle by its ID.
Deactivate User Bundle: Deactivates a user bundle by its ID.
Get User Bundle Resources: Retrieves the resources of a user bundle by its ID.

Voicemail

Get voicemail: Returns the voicemail settings for a phone number
Create voicemail: Create voicemail settings for a phone number
Update voicemail: Update voicemail settings for a phone number

Voice Channels

List your voice channels for non-US zones: Returns the non-US voice channels for your account. voice channels allow you to use Channel Billing for calls to your Telnyx phone numbers. Please check the <a…
Update voice channels for non-US Zones: Update the number of Voice Channels for the Non-US Zones. This allows your account to handle multiple simultaneous inbound calls to Non-US numbers. Use this en…
List your voice channels for US Zone: Returns the US Zone voice channels for your account. voice channels allows you to use Channel Billing for calls to your Telnyx phone numbers. Please check the…
Update voice channels for US Zone: Update the number of Voice Channels for the US Zone. This allows your account to handle multiple simultaneous inbound calls to US numbers. Use this endpoint to…
List All Numbers using Channel Billing: Retrieve a list of all phone numbers using Channel Billing, grouped by Zone.
List Numbers using Channel Billing for a specific Zone: Retrieve a list of phone numbers using Channel Billing for a specific Zone.

Dynamic Emergency Addresses

List dynamic emergency addresses: Returns the dynamic emergency addresses according to filters
Create a dynamic emergency address.: Creates a dynamic emergency address.
Get a dynamic emergency address: Returns the dynamic emergency address based on the ID provided
Delete a dynamic emergency address: Deletes the dynamic emergency address based on the ID provided

Dynamic Emergency Endpoints

List dynamic emergency endpoints: Returns the dynamic emergency endpoints according to filters
Create a dynamic emergency endpoint.: Creates a dynamic emergency endpoints.
Get a dynamic emergency endpoint: Returns the dynamic emergency endpoint based on the ID provided
Delete a dynamic emergency endpoint: Deletes the dynamic emergency endpoint based on the ID provided

Number Lookup

Lookup phone number data: Returns information about the provided phone number.

Verify

Trigger Call verification
Trigger Flash call verification
Trigger SMS verification
Trigger WhatsApp verification
Retrieve verification
Verify verification code by ID
List verifications by phone number
Verify verification code by phone number
List all Verify profiles: Gets a paginated list of Verify profiles.
Create a Verify profile: Creates a new Verify profile to associate verifications with.
Retrieve Verify profile: Gets a single Verify profile.
Update Verify profile
Delete Verify profile
Retrieve Verify profile message templates: List all Verify profile message templates.
Create message template: Create a new Verify profile message template.
Update message template: Update an existing Verify profile message template.

Enterprises

List enterprises: Return the enterprises you own, paginated. The default page size is 20; the maximum is 250.
Create an enterprise: Create the legal entity (enterprise) that represents your business on the Telnyx platform.
Get an enterprise: Retrieve a single enterprise by id. Returns 404 if the id does not exist or does not belong to your account.
Replace an enterprise: Replace the enterprise’s mutable fields. Only mutable fields may be sent. Server-assigned and immutable fields (id, record_type, created_at, updated_at…
Delete an enterprise: Soft-delete an enterprise.

Terms of Service

Agree to the Phone Number Reputation Terms of Service: Records the authenticated user’s agreement to the current Phone Number Reputation ToS. No body required. Idempotent.

Reputation

Get phone-number reputation settings for an enterprise: Phone Number Reputation tracks how your outbound caller-IDs are perceived (spam risk, engagement, etc.) across the call-screening ecosystem. This endpoint read…
Enable phone-number reputation for an enterprise: Activate Phone Number Reputation for the given enterprise. Requires an uploaded Letter of Authorization document (the loa_document_id references the Telnyx D…
Disable phone-number reputation for an enterprise: Disable Phone Number Reputation. All registered numbers are de-registered as a cascade. The enterprise itself is unaffected. Returns 204 on success, 404 if…
Change the reputation refresh frequency: Update how often Telnyx refreshes the reputation data for this enterprise’s registered numbers. The new frequency takes effect on the next scheduled refresh.
Render a phone-number reputation Letter of Authorization: Render the LOA for this enterprise as a PDF. The enterprise identity, address, and authorized-representative contact are taken from the enterprise record; the…
Replace the reputation Letter of Authorization document: Point the enterprise’s reputation settings at a new signed LOA document. This resets LOA approval to pending; the new document must be approved before additi…
List reputation-monitored phone numbers for an enterprise: Paginated list of phone numbers registered for reputation monitoring under this enterprise. The response includes the latest reputation snapshot per number whe…
Register phone numbers for reputation monitoring: Add up to 100 phone numbers to reputation monitoring on this enterprise. Each must be in E.164 format (+1NPANXXXXXX for US/CA) and belong to your Telnyx phon…
Get a single reputation-monitored phone number: Retrieve one registered number with its latest reputation snapshot. The phone_number path parameter is in E.164 format and must be URL-encoded (e.g. `%2B1949…
Remove a phone number from reputation monitoring: Stop tracking the reputation of this phone number. The number itself remains in your inventory; only the reputation registration is removed.
List reputation-monitored phone numbers across all enterprises: Convenience alias for GET /v2/enterprises/{enterprise_id}/reputation/numbers that returns numbers across every enterprise you own. Useful when you don’t want…
Get a reputation-monitored number (no enterprise_id required): Convenience alias for GET /v2/enterprises/{enterprise_id}/reputation/numbers/{phone_number}.
Remove a phone number from reputation monitoring (no enterprise_id required): Convenience alias for DELETE /v2/enterprises/{enterprise_id}/reputation/numbers/{phone_number}.
List reputation remediation requests for an enterprise: Paginated list of remediation requests for this enterprise. List items omit per-number results and webhook URLs to keep the response small; call GET by id for…
Submit phone numbers for reputation remediation: Submit a batch of phone numbers belonging to this enterprise for reputation remediation. The request is accepted asynchronously: this endpoint returns 202 wi…
Get a reputation remediation request: Retrieve the full detail of a remediation request, including current status, per-number results (once available), and submission metadata.

Numbers llms.txt

Global Phone Numbers llms.txt

⌘I

​Telnyx Numbers — Full Documentation

​Global Phone Numbers

​Getting started with Telnyx phone number APIs

​Overview:

​Coverage

​Regulatory Requirements

​Search

​Reserve

​Order

​Advanced Order

​Number search

​Constraints

​Best Practices

​Filter for specific phone numbers

​Required Filters

​Standard Filters

​Advanced Filters

​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

​Porting

​Port in orders

​Overview

​Constraints

​Order splitting

​How it works

​Step 1: Check portability

​Step 2: Create a draft port order

​Step 3: Fulfill the porting order

​Step 4: Submit the port order

​Step 5: Monitor order progress

​Notifications

​Comments

​Additional resources

​Port-in requirements

​Overview

​How it works

​Step 1: View requirements on your port order

​Step 2: Fulfill requirements

​Requirement statuses

​Order-level requirements status

​Allowed FOC dates

​Overview

Telnyx Numbers — Full Documentation

Global Phone Numbers

Getting started with Telnyx phone number APIs

Overview:

Coverage

Regulatory Requirements

Search

Reserve

Order

Advanced Order

Number search

Constraints

Best Practices

Filter for specific phone numbers

Required Filters

Standard Filters

Advanced Filters

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

Porting

Port in orders

Overview

Constraints

Order splitting

How it works

Step 1: Check portability

Step 2: Create a draft port order

Step 3: Fulfill the porting order

Step 4: Submit the port order

Step 5: Monitor order progress

Notifications

Comments

Additional resources

Port-in requirements

Overview

How it works

Step 1: View requirements on your port order

Step 2: Fulfill requirements

Requirement statuses

Order-level requirements status

Allowed FOC dates

Overview