Messaging API Reference: Phone Numbers

List all messaging capable phone numbers

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

JSON
Schema

{
  "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 number

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

string

required

The id of the phone number

Responses

200

Expected phone number response to a valid request

default

Unexpected error

Success Response

JSON
Schema

{
  "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 number

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

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

JSON
Schema

{
  "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"
  }
}

Previous: Messaging Profiles

Next: Short Codes

In query

In path

In path

In body

Was this section helpful?