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 phone numberslistPhoneNumbers

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

List 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"
filter[emergency_address_id]
string (int64)
optional

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

Example: "9102160989215728032"
filter[customer_reference]
string
optional

Filter numbers via the customer_reference set.

Example: "MY REF 001"
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

Successful response with a list of phone numbers.

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",
      "customer_reference": "customer-reference",
      "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
  }
}

Retrieve a phone numberretrievePhoneNumber

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

Retrieve 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

Successful response with details about a 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",
    "customer_reference": "customer-reference",
    "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 a phone numberupdatePhoneNumber

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

Update 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 (application/json)
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.

customer_reference
string
optional

A customer reference string for customer look ups.

Example: "MY REF 001"
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

Successful response with details about a 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",
    "customer_reference": "customer-reference",
    "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

Successful response with details about a 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",
    "customer_reference": "customer-reference",
    "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": "deleted",
    "t38_fax_gateway_enabled": true,
    "tags": [
      "tag_1",
      "tag_2"
    ],
    "updated_at": "2019-10-24T18:10:00.000Z"
  }
}

Retrieve a phone number with voice settingsretrievePhoneNumberWithVoiceSettings

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

Retrieve a phone number with voice 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/1293384261075731499/voice"
Parameters
In path
id
string (int64)
required

Identifies the resource.

Example: "1293384261075731499"
Responses
200

Successful response with details about a phone number including voice settings.

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",
    "customer_reference": "customer_reference",
    "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 a phone number with voice settingsupdatePhoneNumberWithVoiceSettings

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

Update a phone number with voice settings

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 (application/json)
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

Successful response with details about a phone number including voice settings.

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",
    "customer_reference": "customer_reference",
    "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 phone numbers with voice settingslistPhoneNumbersWithVoiceSettings

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

List phone numbers with voice 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/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[customer_reference]
string
optional

Filter numbers via the customer_reference set.

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

Successful response with a list of phone numbers with voice settings.

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",
      "customer_reference": "customer_reference",
      "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"
    }
  ],
  "meta": {
    "page_number": 2,
    "page_size": 25,
    "total_pages": 3,
    "total_results": 55
  }
}

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 (application/json)
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

Phone 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",
    "customer_reference": "customer_reference",
    "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 phone numbers with messaging settingslistPhoneNumbersWithMessagingSettings

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

List phone numbers with 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"
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
Responses
200

Successful response with a list of phone numbers with messaging settings.

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 a phone number with messaging settingsretrievePhoneNumberWithMessagingSettings

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

Retrieve a phone number with 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/{id}/messaging"
Parameters
In path
id
string
required

Identifies the type of resource.

Responses
200

Successful response with details about a phone number including voice settings.

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 a phone number with messaging settingsupdatePhoneNumberWithMessagingSettings

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

Update a phone number with messaging settings

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 (application/json)
messaging_product
string
optional

The requested messaging product the number should be on

Example: "P2P"
messaging_profile_id
string
optional

Unique identifier for a messaging profile.

Responses
200

Successful response with details about a phone number including voice settings.

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?