This is the API V2 documentation. To switch out of beta revert back to our API V1.

Open SidemenuAPI Reference
API Reference
Close Sidemenu

Phone Numbers

List all messaging capable phone numberslistMessagingPhoneNumbers

get https://api.telnyx.com/v2/messaging_phone_numbers

List all messaging capable phone numbers

curl -X GET \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --globoff "https://api.telnyx.com/v2/messaging_phone_numbers?page[size]=10"
Parameters
In query
page[number]
integer (1)
optional

The page number to load

Default: 1
page[size]
integer (1- 250)
optional

The size of the page

Default: 20
filter[messaging_profile_id]
string
optional

Filter by Messaging Profile ID. Use the string `null` for phone numbers without assigned profiles. A synonym for the `/messaging_profiles/{id}/phone_number` endpoint when querying about an extant profile.

filter[phone_number]
string
optional

A comma separated list of phone numbers to return

Responses
200

A paginated array of the phone numbers

default

Unexpected error

Success Response
{
  "data": [
    {
      "country_code": "US",
      "created_at": "2019-01-23T18:10:02.574Z",
      "eligible_messaging_products": [
        "A2P"
      ],
      "features": {
        "mms": null,
        "sms": {
          "domestic_two_way": true,
          "international_inbound": true,
          "international_outbound": true
        }
      },
      "health": {
        "inbound_outbound_ratio": 0.43,
        "message_count": 122,
        "spam_ratio": 0.06,
        "success_ratio": 0.94
      },
      "id": "+18665550001",
      "messaging_product": "A2P",
      "messaging_profile_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "phone_number": "+18005550001",
      "record_type": "messaging_phone_number",
      "traffic_type": "A2P",
      "type": "toll-free",
      "updated_at": "2019-01-23T18:10:02.574Z"
    }
  ],
  "meta": {
    "page_number": 2,
    "page_size": 25,
    "total_pages": 3,
    "total_results": 55
  }
}

Retrieve a messaging phone numberretrieveMessagingPhoneNumber

get https://api.telnyx.com/v2/messaging_phone_numbers/{id}

Retrieve a messaging phone number

curl -X GET \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --globoff "https://api.telnyx.com/v2/messaging_phone_numbers/{id}"
Parameters
In path
id
string
required

The id of the phone number

Responses
200

Expected phone number response to a valid request

default

Unexpected error

Success Response
{
  "data": {
    "country_code": "US",
    "created_at": "2019-01-23T18:10:02.574Z",
    "eligible_messaging_products": [
      "A2P"
    ],
    "features": {
      "mms": null,
      "sms": {
        "domestic_two_way": true,
        "international_inbound": true,
        "international_outbound": true
      }
    },
    "health": {
      "inbound_outbound_ratio": 0.43,
      "message_count": 122,
      "spam_ratio": 0.06,
      "success_ratio": 0.94
    },
    "id": "+18665550001",
    "messaging_product": "A2P",
    "messaging_profile_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "phone_number": "+18005550001",
    "record_type": "messaging_phone_number",
    "traffic_type": "A2P",
    "type": "toll-free",
    "updated_at": "2019-01-23T18:10:02.574Z"
  }
}

Update a messaging phone numberupdateMessagingPhoneNumber

patch https://api.telnyx.com/v2/messaging_phone_numbers/{id}

Update the settings for a specific number. To unbind a number from, a profile, set the messaging_profile_id to null or an empty string.

curl -X PATCH \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --data '{"messaging_profile_id": "uuid"}' \
  https://api.telnyx.com/v2/messaging_phone_numbers/{id}
Parameters
In path
id
string
required

The id of the phone number

In body
messaging_product
string
optional

The requested messaging product the number should be on

Example: "P2P"
messaging_profile_id
string (uuid)
optional

Unique identifier for a messaging profile.

Responses
200

Expected phone number response to a valid request

default

Unexpected error

Success Response
{
  "data": {
    "country_code": "US",
    "created_at": "2019-01-23T18:10:02.574Z",
    "eligible_messaging_products": [
      "A2P"
    ],
    "features": {
      "mms": null,
      "sms": {
        "domestic_two_way": true,
        "international_inbound": true,
        "international_outbound": true
      }
    },
    "health": {
      "inbound_outbound_ratio": 0.43,
      "message_count": 122,
      "spam_ratio": 0.06,
      "success_ratio": 0.94
    },
    "id": "+18665550001",
    "messaging_product": "A2P",
    "messaging_profile_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "phone_number": "+18005550001",
    "record_type": "messaging_phone_number",
    "traffic_type": "A2P",
    "type": "toll-free",
    "updated_at": "2019-01-23T18:10:02.574Z"
  }
}

Was this section helpful?was-this-page-helpful