Skip to main content

Retrieve all 'TN's


Retrieve messaging settings for all phone numbers. In terminology specific to Telnyx Messaging: this endpoint returns a list of TNs.

When a request to is successful, the response payload will contain one TN (represented as a JSON object) per phone number – as shown in the example below.

"num": "+13129457420",
"user_id": "834f3d53-8a3c-4aa0-a733-7f2d682a72df",
"profile_id": "16fd2706-8baf-433b-82eb-8c7fada847da",
"last_updated": 1521566241103171,
"country_code": null,
"campaign_id": null,
"num_country": "USA"

For fuller details on a TN, request the resource directly. For example, would return the following:

"num": "+13129457420",
"user_id": "834f3d53-8a3c-4aa0-a733-7f2d682a72df",
"profile_id": "16fd2706-8baf-433b-82eb-8c7fada847da",
"last_updated": 1521566241103171,
"country_code": null,
"campaign_id": null,
"num_country": "USA",
"traffic_type": "A2P",
"num_type": "long-code",
"sms": {
"enabled": true,
"domestic_two_way": true,
"international_inbound": true,
"international_outbound": true
"mms": null

In the Telnyx Messaging API, the TN resource tracks the messaging settings that can be configured on your phone numbers.

To enable messaging on a phone number, update its messaging TN to associate it with one of your existing messaging profiles.

Note that not all phone numbers are messaging-capable. In such cases, when you attempt to enable messaging on the TN, you will receive a 40323 error.

Configuration & usage overview:

  • profile_id is the only TN field that you need to configure.
  • Configuring a profile-level webhook is like setting a default callback URL for phone numbers assigned to that profile.

Field-specific information:




Default: ""

UUID returned as a string.

e.g., "c51c89d9-68ad-4db2-a471-cf622d21c40d"



ID of the messaging profile to which the phone number is current assigned.

In order to use the Telnyx Messaging Services, you need to create at least one messaging profile.

An SMS-capable phone number is SMS-enabled only when it is assigned to an existing messaging profile.


Updated at time in Unix time in microseconds,
returned as a 16-digit integer
(1 μs = 10-6 sec).

When unknown, last_updated = 0.

e.g., 1521566241103171 is Tue, 20 Mar 2018 17:17:21 UTC




The messaging campaign ID associated with the shortcode.

Only used for shortcodes.


The ISO 3166-1 alpha-3 country code of the country of origin for the number.


The messaging product type the number is registered with.

Possible values, "A2P" and "P2P"


The type of number.

Possible values include: "long-code", "toll-free", "short-code", etc.


A nullable object that lists the possible SMS features of the number.

If present and enabled is true, SMS is enabled on the number.

If present and enabled is false, SMS is capable, but not enabled on the number.

If not present, the number is not SMS capable.


A nullable object that lists the possible MMS features of the number.

If present and enabled is true, MMS is enabled on the number.

If present and enabled is false, MMS is capable, but not enabled on the number.

If not present, the number is not MMS capable.

Messaging Products

There are different use cases for needing to send SMS and MMS messages. To more closely match with your needs, Telnyx offers 2 messaging product types: A2P (application to person) and P2P (person to person).

A2P traffic is geared mainly for high volume one way traffic. Appointment reminders, temporary password tokens, promotional offers, etc.

P2P traffic is more conversational traffic with high levels of engagement from the end device. Customer support, chatbots, etc.

When you first enable messaging on a number, Telnyx will automatically default to a specific messaging product based on the type of number you are messaging enabling. After a certain threshold of usage, Telnyx will offer users the ability to request a messaging product change on a number. Telnyx will verify the number exhibits the behavior of the requested messaging product type. If it does not, the request will be rejected.

Requesting a Messaging Product Change

For a detailed guide on requesting a messaging product see our guide: Requesting a Messaging Product Change

Retrieve all 'TN's: request-response scheme


Query Parameters

    has_messaging_profile boolean

    Filter results to include only phone numbers with an assigned messaging profile


200: List of 'TN's