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

Telnyx DevelopersAPI v2
Sign inTelnyx Developers
Open Menu
DocsAPI ReferenceJoin Slack Community
Create an AccountSign in
Questions on setup? Talk to our experts
Open SidemenuAPI Reference
API Reference
Close Sidemenu

Number Configurations

List all phone numbersfindPhoneNumbers

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

List all 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/phone_numbers?page[size]=10&filter[tag]=region_5&filter[phone_number]=+19705555098"
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[tag]
string
optional

Filter by phone number tags

filter[phone_number]
string
optional

Filter by phone number. Requires at least three digits. Non-numerical characters will result in no values being returned.

filter[status]
string
optional

Filter by phone number status

Example: "active"
Options: [ "purchase_pending", "purchase_failed", "port_pending", "active", "deleted", "port_failed", "emergency_only", "ported_out", "port_out_pending" ]
filter[voice.connection_name][contains]
string
optional

Filter contains connection name. Requires at least three characters

Example: "test"
filter[voice.connection_name][starts_with]
string
optional

Filter starts with connection name. Requires at least three characters

Example: "test"
filter[voice.connection_name][ends_with]
string
optional

Filter ends with connection name. Requires at least three characters

Example: "test"
filter[voice.connection_name][eq]
string
optional

Filter by connection name

Example: "test"
filter[usage_payment_method]
string
optional

Filter by usage_payment_method.

Example: "channel"
Options: [ "pay-per-minute", "channel" ]
filter[billing_group_id]
string
optional

Filter by the billing_group_id associated with phone numbers. To filter to only phone numbers that have no billing group associated them, set the value of this filter to the string 'null'.

Example: "62e4bf2e-c278-4282-b524-488d9c9c43b2"
sort
string
optional

Specifies the sort order for results. If not given, results are sorted by created_at in descending order

Example: "connection_name"
Options: [ "purchased_at", "phone_number", "connection_name", "usage_payment_method" ]
Responses
200

A paginated array of PhoneNumbers.

default

Unexpected error

Success Response
{
  "data": [
    {
      "billing_group_id": "86f58db9-0fe3-4adc-9d1f-46e66e6e9323",
      "call_forwarding_enabled": true,
      "call_recording_enabled": true,
      "caller_id_name_enabled": true,
      "cnam_listing_enabled": true,
      "connection_id": "1293384261075731499",
      "connection_name": "connection-name",
      "created_at": "2019-10-23T18:10:00.000Z",
      "emergency_address_id": "1315261609962112019",
      "emergency_enabled": true,
      "external_pin": "1234",
      "id": "1293384261075731499",
      "messaging_profile_id": "abc85f64-5717-4562-b3fc-2c9600000000",
      "messaging_profile_name": "regional-customers",
      "phone_number": "+19705555098",
      "purchased_at": "2019-10-23T18:10:00.000Z",
      "record_type": "phone_number",
      "status": "active",
      "t38_fax_gateway_enabled": true,
      "tags": [
        "tag_1",
        "tag_2"
      ],
      "updated_at": "2019-10-24T18:10:00.000Z"
    }
  ],
  "meta": {
    "page_number": 2,
    "page_size": 25,
    "total_pages": 3,
    "total_results": 55
  }
}

Get the settings for a phone numbergetPhoneNumber

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

Get the settings for a 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/phone_numbers/1293384261075731499"
Parameters
In path
id
string (int64)
required

Identifies the resource.

Example: "1293384261075731499"
Responses
200

The details for a single phone number.

default

Unexpected error

Success Response
{
  "data": {
    "billing_group_id": "86f58db9-0fe3-4adc-9d1f-46e66e6e9323",
    "call_forwarding_enabled": true,
    "call_recording_enabled": true,
    "caller_id_name_enabled": true,
    "cnam_listing_enabled": true,
    "connection_id": "1293384261075731499",
    "connection_name": "connection-name",
    "created_at": "2019-10-23T18:10:00.000Z",
    "emergency_address_id": "1315261609962112019",
    "emergency_enabled": true,
    "external_pin": "1234",
    "id": "1293384261075731499",
    "messaging_profile_id": "abc85f64-5717-4562-b3fc-2c9600000000",
    "messaging_profile_name": "regional-customers",
    "phone_number": "+19705555098",
    "purchased_at": "2019-10-23T18:10:00.000Z",
    "record_type": "phone_number",
    "status": "active",
    "t38_fax_gateway_enabled": true,
    "tags": [
      "tag_1",
      "tag_2"
    ],
    "updated_at": "2019-10-24T18:10:00.000Z"
  }
}

Update the settings for a phone numberupdatePhoneNumber

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

Update the settings for a phone number

curl -X PATCH \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --data '{"tags": ["region_5"]}' \
  https://api.telnyx.com/v2/phone_numbers/1293384261075731499
Parameters
In path
id
string (int64)
required

Identifies the resource.

Example: "1293384261075731499"
In body
billing_group_id
string
optional

Identifies the billing group associated with the phone number.

connection_id
string
optional

Identifies the connection associated with the phone number.

external_pin
string
optional

If someone attempts to port your phone number away from Telnyx and your phone number has an external PIN set, we will attempt to verify that you provided the correct external PIN to the winning carrier. Note that not all carriers cooperate with this security mechanism.

tags
array of string
optional

A list of user-assigned tags to help organize phone numbers.

Responses
200

The details for a single phone number.

default

Unexpected error

Success Response
{
  "data": {
    "billing_group_id": "86f58db9-0fe3-4adc-9d1f-46e66e6e9323",
    "call_forwarding_enabled": true,
    "call_recording_enabled": true,
    "caller_id_name_enabled": true,
    "cnam_listing_enabled": true,
    "connection_id": "1293384261075731499",
    "connection_name": "connection-name",
    "created_at": "2019-10-23T18:10:00.000Z",
    "emergency_address_id": "1315261609962112019",
    "emergency_enabled": true,
    "external_pin": "1234",
    "id": "1293384261075731499",
    "messaging_profile_id": "abc85f64-5717-4562-b3fc-2c9600000000",
    "messaging_profile_name": "regional-customers",
    "phone_number": "+19705555098",
    "purchased_at": "2019-10-23T18:10:00.000Z",
    "record_type": "phone_number",
    "status": "active",
    "t38_fax_gateway_enabled": true,
    "tags": [
      "tag_1",
      "tag_2"
    ],
    "updated_at": "2019-10-24T18:10:00.000Z"
  }
}

Delete a phone numberdeletePhoneNumber

delete https://api.telnyx.com/v2/phone_numbers/{id}

Delete a phone number

curl -X DELETE \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  "https://api.telnyx.com/v2/phone_numbers/1293384261075731499"
Parameters
In path
id
string (int64)
required

Identifies the resource.

Example: "1293384261075731499"
Responses
200

The details for the phone number that was just deleted.

default

Unexpected error

Success Response
{
  "data": {
    "billing_group_id": "86f58db9-0fe3-4adc-9d1f-46e66e6e9323",
    "call_forwarding_enabled": true,
    "call_recording_enabled": true,
    "caller_id_name_enabled": true,
    "cnam_listing_enabled": true,
    "connection_id": "1293384261075731499",
    "connection_name": "connection-name",
    "created_at": "2019-10-23T18:10:00.000Z",
    "emergency_address_id": "1315261609962112019",
    "emergency_enabled": true,
    "external_pin": "1234",
    "id": "1293384261075731499",
    "messaging_profile_id": "abc85f64-5717-4562-b3fc-2c9600000000",
    "messaging_profile_name": "regional-customers",
    "phone_number": "+19705555098",
    "purchased_at": "2019-10-23T18:10:00.000Z",
    "record_type": "phone_number",
    "status": "active",
    "t38_fax_gateway_enabled": true,
    "tags": [
      "tag_1",
      "tag_2"
    ],
    "updated_at": "2019-10-24T18:10:00.000Z"
  }
}

Get the voice settings for a phone numberretrievePhoneNumberVoice

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

Get the voice settings for a 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/phone_numbers/1293384261075731499/voice"
Parameters
In path
id
string (int64)
required

Identifies the resource.

Example: "1293384261075731499"
Responses
200

The voice attributes and information for a phone number.

default

Unexpected error

Success Response
{
  "data": {
    "call_forwarding": {
      "call_forwarding_enabled": true,
      "forwarding_type": "always",
      "forwards_to": "+13035559123"
    },
    "call_recording": {
      "inbound_call_recording_channels": "single",
      "inbound_call_recording_enabled": true,
      "inbound_call_recording_format": "wav"
    },
    "cnam_listing": {
      "cnam_listing_details": "example",
      "cnam_listing_enabled": true
    },
    "connection_id": "1d0e6cb8-8668-462e-94c6-49ae0f0ed48b",
    "emergency": {
      "emergency_address_id": "1315261609962112019",
      "emergency_enabled": true
    },
    "id": "1293384261075731499",
    "media_features": {
      "accept_any_rtp_packets_enabled": true,
      "media_handling_mode": "default",
      "rtp_auto_adjust_enabled": true,
      "t38_fax_gateway_enabled": true
    },
    "record_type": "voice_settings",
    "tech_prefix_enabled": false,
    "translated_number": "+13035559999",
    "usage_payment_method": "pay-per-minute"
  }
}

Update the voice settings for a phone numberupdatePhoneNumberVoice

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

Update the voice settings for a phone number

curl -X PATCH \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --data '{ "tech_prefix_enabled": true }' \
  https://api.telnyx.com/v2/phone_numbers/1293384261075731499/voice
Parameters
In path
id
string (int64)
required

Identifies the resource.

Example: "1293384261075731499"
In body
call_forwarding
object
optional

The call forwarding settings for a phone number.

Example: { "call_forwarding_enabled": true, "forwarding_type": "always", "forwards_to": "+13035559123" }
call_recording
object
optional

The call recording settings for a phone number.

Example: { "inbound_call_recording_channels": "single", "inbound_call_recording_enabled": true, "inbound_call_recording_format": "wav" }
cnam_listing
object
optional

The CNAM listing settings for a phone number.

Example: { "cnam_listing_details": "example", "cnam_listing_enabled": true }
media_features
object
optional

The media features settings for a phone number.

Example: { "accept_any_rtp_packets_enabled": true, "media_handling_mode": "default", "rtp_auto_adjust_enabled": true, "t38_fax_gateway_enabled": true }
tech_prefix_enabled
boolean
optional

Controls whether a tech prefix is enabled for this phone number.

Default: false
translated_number
string
optional

This field allows you to rewrite the destination number of an inbound call before the call is routed to you. The value of this field may be any alphanumeric value, and the value will replace the number originally dialed.

usage_payment_method
string
optional

Controls whether a number is billed per minute or uses your concurrent channels.

Default: "pay-per-minute"
Options: [ "pay-per-minute", "channel" ]
Responses
200

The voice attributes and information for a phone number.

default

Unexpected error

Success Response
{
  "data": {
    "call_forwarding": {
      "call_forwarding_enabled": true,
      "forwarding_type": "always",
      "forwards_to": "+13035559123"
    },
    "call_recording": {
      "inbound_call_recording_channels": "single",
      "inbound_call_recording_enabled": true,
      "inbound_call_recording_format": "wav"
    },
    "cnam_listing": {
      "cnam_listing_details": "example",
      "cnam_listing_enabled": true
    },
    "connection_id": "1d0e6cb8-8668-462e-94c6-49ae0f0ed48b",
    "emergency": {
      "emergency_address_id": "1315261609962112019",
      "emergency_enabled": true
    },
    "id": "1293384261075731499",
    "media_features": {
      "accept_any_rtp_packets_enabled": true,
      "media_handling_mode": "default",
      "rtp_auto_adjust_enabled": true,
      "t38_fax_gateway_enabled": true
    },
    "record_type": "voice_settings",
    "tech_prefix_enabled": false,
    "translated_number": "+13035559999",
    "usage_payment_method": "pay-per-minute"
  }
}

List voice settings for multiple phone numbersfindPhoneNumberVoices

get https://api.telnyx.com/v2/phone_numbers/voice

List voice settings for multiple 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/phone_numbers/voice?page[size]=10&filter[phone_number]=+1312"
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[phone_number]
string
optional

Filter by phone number. Requires at least three digits. Non-numerical characters will result in no values being returned.

filter[connection_name][contains]
string
optional

Filter contains connection name. Requires at least three characters

Example: "test"
filter[usage_payment_method]
string
optional

Filter by usage_payment_method.

Example: "channel"
Options: [ "pay-per-minute", "channel" ]
sort
string
optional

Specifies the sort order for results. If not given, results are sorted by created_at in descending order

Example: "connection_name"
Options: [ "purchased_at", "phone_number", "connection_name", "usage_payment_method" ]
Responses
200

A paginated array of phone number voice information.

default

Unexpected error

Success Response
{
  "data": [
    {
      "call_forwarding": {
        "call_forwarding_enabled": true,
        "forwarding_type": "always",
        "forwards_to": "+13035559123"
      },
      "call_recording": {
        "inbound_call_recording_channels": "single",
        "inbound_call_recording_enabled": true,
        "inbound_call_recording_format": "wav"
      },
      "cnam_listing": {
        "cnam_listing_details": "example",
        "cnam_listing_enabled": true
      },
      "connection_id": "1d0e6cb8-8668-462e-94c6-49ae0f0ed48b",
      "emergency": {
        "emergency_address_id": "1315261609962112019",
        "emergency_enabled": true
      },
      "id": "1293384261075731499",
      "media_features": {
        "accept_any_rtp_packets_enabled": true,
        "media_handling_mode": "default",
        "rtp_auto_adjust_enabled": true,
        "t38_fax_gateway_enabled": true
      },
      "record_type": "voice_settings",
      "tech_prefix_enabled": false,
      "translated_number": "+13035559999",
      "usage_payment_method": "pay-per-minute"
    }
  ]
}

Enable emergency for a phone numberenableEmergencyPhoneNumber

post https://api.telnyx.com/v2/phone_numbers/{id}/actions/enable_emergency

Enable emergency for a phone number

curl -X POST \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --data '{"emergency_address_id":"53829456729313","emergency_enabled":true}' \
  https://api.telnyx.com/v2/phone_numbers/1293384261075731499/actions/enable_emergency
Parameters
In path
id
string (int64)
required

Identifies the resource.

Example: "1293384261075731499"
In body
emergency_address_id
string (int64)
required

Identifies the address to be used with emergency services.

emergency_enabled
boolean
required

Indicates whether to enable emergency services on this number.

Responses
200

Phone number emergency enabled.

202

Number emergency requested.

default

Unexpected error

Success Response
{
  "data": {
    "call_forwarding": {
      "call_forwarding_enabled": true,
      "forwarding_type": "always",
      "forwards_to": "+13035559123"
    },
    "call_recording": {
      "inbound_call_recording_channels": "single",
      "inbound_call_recording_enabled": true,
      "inbound_call_recording_format": "wav"
    },
    "cnam_listing": {
      "cnam_listing_details": "example",
      "cnam_listing_enabled": true
    },
    "connection_id": "1d0e6cb8-8668-462e-94c6-49ae0f0ed48b",
    "emergency": {
      "emergency_address_id": "1315261609962112019",
      "emergency_enabled": true
    },
    "id": "1293384261075731499",
    "media_features": {
      "accept_any_rtp_packets_enabled": true,
      "media_handling_mode": "default",
      "rtp_auto_adjust_enabled": true,
      "t38_fax_gateway_enabled": true
    },
    "record_type": "voice_settings",
    "tech_prefix_enabled": false,
    "translated_number": "+13035559999",
    "usage_payment_method": "pay-per-minute"
  }
}

List all phone numbers' messaging settingslistPhoneNumberMessagingSettings

get https://api.telnyx.com/v2/phone_numbers/messaging

List all phone numbers' messaging settings

curl -X GET \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --globoff "https://api.telnyx.com/v2/phone_numbers/messaging?page[size]=10&filter[phone_number]=+1312"
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": "1293384261075731499",
      "messaging_product": "A2P",
      "messaging_profile_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "phone_number": "+18005550001",
      "record_type": "messaging_settings",
      "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 the messaging settings for a phone numberretrievePhoneNumberMessagingSettings

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

Retrieve the messaging settings for a 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/phone_numbers/{id}/messaging"
Parameters
In path
id
string
required

Identifies the type of resource.

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": "1293384261075731499",
    "messaging_product": "A2P",
    "messaging_profile_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "phone_number": "+18005550001",
    "record_type": "messaging_settings",
    "traffic_type": "A2P",
    "type": "toll-free",
    "updated_at": "2019-01-23T18:10:02.574Z"
  }
}

Update the messaging settings for a phone numberupdatePhoneNumberMessagingSettings

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

Update the messaging settings for a phone number

curl -X PATCH \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --data '{"messaging_profile_id": "e51f3bde-l4b7-464d-bc90-47196f9dd36b"}' \
  https://api.telnyx.com/v2/phone_numbers/{id}/messaging
Parameters
In path
id
string
required

Identifies the type of resource.

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": "1293384261075731499",
    "messaging_product": "A2P",
    "messaging_profile_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "phone_number": "+18005550001",
    "record_type": "messaging_settings",
    "traffic_type": "A2P",
    "type": "toll-free",
    "updated_at": "2019-01-23T18:10:02.574Z"
  }
}

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