Number Configurations API

Configure your phone numbers API

List phone numbers

SecuritybearerAuth
Request
query Parameters
page[number]
integer >= 1
Default: 1

The page number to load

page[size]
integer [ 1 .. 250 ]
Default: 20

The size of the page

filter[tag]
string

Filter by phone number tags.

filter[phone_number]
string

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

filter[status]
string

Filter by phone number status.

Enum: "purchase_pending" "purchase_failed" "port_pending" "active" "deleted" "port_failed" "emergency_only" "ported_out" "port_out_pending"
Example: filter[status]=active
filter[connection_id]
string <int64>

Filter by connection_id.

Example: filter[connection_id]=1521916448077776306
filter[voice.connection_name][contains]
string

Filter contains connection name. Requires at least three characters.

Example: filter[voice.connection_name][contains]=test
filter[voice.connection_name][starts_with]
string

Filter starts with connection name. Requires at least three characters.

Example: filter[voice.connection_name][starts_with]=test
filter[voice.connection_name][ends_with]
string

Filter ends with connection name. Requires at least three characters.

Example: filter[voice.connection_name][ends_with]=test
filter[voice.connection_name][eq]
string

Filter by connection name.

Example: filter[voice.connection_name][eq]=test
filter[usage_payment_method]
string

Filter by usage_payment_method.

Enum: "pay-per-minute" "channel"
Example: filter[usage_payment_method]=channel
filter[billing_group_id]
string

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: filter[billing_group_id]=62e4bf2e-c278-4282-b524-488d9c9c43b2
filter[emergency_address_id]
string <int64>

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: filter[emergency_address_id]=9102160989215728032
filter[customer_reference]
string

Filter numbers via the customer_reference set.

sort
string

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

Enum: "purchased_at" "phone_number" "connection_name" "usage_payment_method"
Example: sort=connection_name
Responses
200

Successful response with a list of phone numbers.

Response Schema: application/json
Array of objects (PhoneNumberDetailed)
object (PaginationMeta)
default

Unexpected error

Response Schema: application/json
Array of objects (Error)
Array
code
required
string <int>
detail
string
meta
object
object
title
required
string
get/phone_numbers
Request samples 
import telnyx
telnyx.api_key = "YOUR_API_KEY"

telnyx.PortingPhoneNumber.list(page: { numbner: 1, size: 20})
Response samples
application/json
{
  • "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",
      • "number_level_routing": "disabled",
      • "phone_number": "+19705555098",
      • "phone_number_type": "local",
      • "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
    }
}

List phone numbers with messaging settings

SecuritybearerAuth
Request
query Parameters
page[number]
integer >= 1
Default: 1

The page number to load

page[size]
integer [ 1 .. 250 ]
Default: 20

The size of the page

Responses
200

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

Response Schema: application/json
Array of objects (PhoneNumberWithMessagingSettings)
object (PaginationMeta)
default

Unexpected error

Response Schema: application/json
Array of objects (Error)
Array
code
required
string <int>
detail
string
meta
object
object
title
required
string
get/phone_numbers/messaging
Request samples 
import telnyx
telnyx.api_key = "YOUR_API_KEY"

telnyx.MessagingPhoneNumber.list(page={"number":1, "size":20})
Response samples
application/json
{
  • "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
    }
}

List phone numbers with voice settings

SecuritybearerAuth
Request
query Parameters
page[number]
integer >= 1
Default: 1

The page number to load

page[size]
integer [ 1 .. 250 ]
Default: 20

The size of the page

filter[phone_number]
string

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

filter[connection_name][contains]
string

Filter contains connection name. Requires at least three characters.

Example: filter[connection_name][contains]=test
filter[customer_reference]
string

Filter numbers via the customer_reference set.

filter[usage_payment_method]
string

Filter by usage_payment_method.

Enum: "pay-per-minute" "channel"
Example: filter[usage_payment_method]=channel
sort
string

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

Enum: "purchased_at" "phone_number" "connection_name" "usage_payment_method"
Example: sort=connection_name
Responses
200

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

Response Schema: application/json
Array of objects (PhoneNumberWithVoiceSettings)
object (PaginationMeta)
default

Unexpected error

Response Schema: application/json
Array of objects (Error)
Array
code
required
string <int>
detail
string
meta
object
object
title
required
string
get/phone_numbers/voice
Request samples 
import telnyx
telnyx.api_key = "YOUR_API_KEY"

telnyx.PhoneNumbers.list_voice.list(page={"number":1,"size":20})
Response samples
application/json
{
  • "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,
        • "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
    }
}

Delete a phone number

SecuritybearerAuth
Request
path Parameters
id
required
string <int64>

Identifies the resource.

Example: 1293384261075731499
Responses
200

Successful response with details about a phone number.

Response Schema: application/json
object (PhoneNumberDeletedDetailed)
billing_group_id
string

Identifies the billing group associated with the phone number.

call_forwarding_enabled
boolean
Default: true

Indicates if call forwarding will be enabled for this number if forwards_to and forwarding_type are filled in. Defaults to true for backwards compatibility with APIV1 use of numbers endpoints.

call_recording_enabled
boolean

Indicates whether call recording is enabled for this number.

caller_id_name_enabled
boolean

Indicates whether caller ID is enabled for this number.

cnam_listing_enabled
boolean

Indicates whether a CNAM listing is enabled for this number.

connection_id
string

Identifies the connection associated with the phone number.

connection_name
string

The user-assigned name of the connection to be associated with this phone number.

created_at
string

ISO 8601 formatted date indicating when the time it took to activate after the purchase.

customer_reference
string

A customer reference string for customer look ups.

emergency_address_id
string <int64>

Identifies the emergency address associated with the phone number.

emergency_enabled
boolean

Indicates whether emergency services are enabled for this number.

external_pin
string

If someone attempts to port your phone number away from Telnyx and your phone number has an external PIN set, Telnyx 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.

id
string <int64> (IntId)

Uniquely identifies the resource.

messaging_profile_id
string

Identifies the messaging profile associated with the phone number.

messaging_profile_name
string

The name of the messaging profile associated with the phone number.

number_level_routing
string
Default: "disabled"

Specifies whether the number can have overrides to the routing settings on itself (enabled) or if it uses the associated connection for all routing settings (disabled). Defaults to disabled or the value set on your user profile in default_number_routing_setting. There are performance advantages to using disabled and setting all routing information at the connection level.

Enum: "enabled" "disabled"
phone_number
string

The +E.164-formatted phone number associated with this record.

phone_number_type
string

The phone number's type.

Enum: "local" "toll_free" "mobile" "national" "shared_cost" "landline"
purchased_at
string

ISO 8601 formatted date indicating the time the request was made to purchase the number.

record_type
string

Identifies the type of the resource.

status
string

The phone number's current status.

Enum: "purchase-pending" "purchase-failed" "port-pending" "port-failed" "active" "deleted" "emergency-only" "ported-out" "port-out-pending"
t38_fax_gateway_enabled
boolean

Indicates whether T38 Fax Gateway for inbound calls to this number.

tags
Array of strings

A list of user-assigned tags to help manage the phone number.

updated_at
string

ISO 8601 formatted date indicating when the resource was updated.

default

Unexpected error

Response Schema: application/json
Array of objects (Error)
Array
code
required
string <int>
detail
string
meta
object
object
title
required
string
delete/phone_numbers/{id}
Request samples 
import telnyx
telnyx.api_key = "YOUR_API_KEY"

res = telnyx.PhoneNumber.retrieve('id')
res.delete()
Response samples
application/json
{
  • "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",
    • "number_level_routing": "disabled",
    • "phone_number": "+19705555098",
    • "phone_number_type": "local",
    • "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

SecuritybearerAuth
Request
path Parameters
id
required
string <int64>

Identifies the resource.

Example: 1293384261075731499
Responses
200

Successful response with details about a phone number.

Response Schema: application/json
object (PhoneNumberDetailed)
billing_group_id
string

Identifies the billing group associated with the phone number.

call_forwarding_enabled
boolean
Default: true

Indicates if call forwarding will be enabled for this number if forwards_to and forwarding_type are filled in. Defaults to true for backwards compatibility with APIV1 use of numbers endpoints.

call_recording_enabled
boolean

Indicates whether call recording is enabled for this number.

caller_id_name_enabled
boolean

Indicates whether caller ID is enabled for this number.

cnam_listing_enabled
boolean

Indicates whether a CNAM listing is enabled for this number.

connection_id
string

Identifies the connection associated with the phone number.

connection_name
string

The user-assigned name of the connection to be associated with this phone number.

created_at
string

ISO 8601 formatted date indicating when the resource was created.

customer_reference
string

A customer reference string for customer look ups.

emergency_address_id
string <int64>

Identifies the emergency address associated with the phone number.

emergency_enabled
boolean

Indicates whether emergency services are enabled for this number.

external_pin
string

If someone attempts to port your phone number away from Telnyx and your phone number has an external PIN set, Telnyx 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.

id
string <int64> (IntId)

Uniquely identifies the resource.

messaging_profile_id
string

Identifies the messaging profile associated with the phone number.

messaging_profile_name
string

The name of the messaging profile associated with the phone number.

number_level_routing
string
Default: "disabled"

Specifies whether the number can have overrides to the routing settings on itself (enabled) or if it uses the associated connection for all routing settings (disabled). Defaults to disabled or the value set on your user profile in default_number_routing_setting. There are performance advantages to using disabled and setting all routing information at the connection level.

Enum: "enabled" "disabled"
phone_number
string

The +E.164-formatted phone number associated with this record.

phone_number_type
string

The phone number's type.

Enum: "local" "toll_free" "mobile" "national" "shared_cost" "landline"
purchased_at
string

ISO 8601 formatted date indicating when the resource was purchased.

record_type
string

Identifies the type of the resource.

status
string

The phone number's current status.

Enum: "purchase-pending" "purchase-failed" "port-pending" "port-failed" "active" "deleted" "emergency-only" "ported-out" "port-out-pending"
t38_fax_gateway_enabled
boolean

Indicates whether T38 Fax Gateway for inbound calls to this number.

tags
Array of strings

A list of user-assigned tags to help manage the phone number.

default

Unexpected error

Response Schema: application/json
Array of objects (Error)
Array
code
required
string <int>
detail
string
meta
object
object
title
required
string
get/phone_numbers/{id}
Request samples 
import telnyx
telnyx.api_key = "YOUR_API_KEY"

telnyx.PhoneNumber.retrieve("id")
Response samples
application/json
{
  • "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",
    • "number_level_routing": "disabled",
    • "phone_number": "+19705555098",
    • "phone_number_type": "local",
    • "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 number

SecuritybearerAuth
Request
path Parameters
id
required
string <int64>

Identifies the resource.

Example: 1293384261075731499
Request Body schema: application/json
required

Updated settings for the phone number.

billing_group_id
string

Identifies the billing group associated with the phone number.

connection_id
string

Identifies the connection associated with the phone number.

customer_reference
string

A customer reference string for customer look ups.

external_pin
string

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.

number_level_routing
string
Default: "enabled"

Specifies whether the number can have overrides to the routing settings on itself (enabled) or if it uses the associated connection for all routing settings (disabled). Defaults to enabled but will be changed to disabled in the future. There are performance advantages to using disabled and setting all routing information at the connection level.

Enum: "enabled" "disabled"
tags
Array of strings

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

Responses
200

Successful response with details about a phone number.

Response Schema: application/json
object (PhoneNumberDetailed)
billing_group_id
string

Identifies the billing group associated with the phone number.

call_forwarding_enabled
boolean
Default: true

Indicates if call forwarding will be enabled for this number if forwards_to and forwarding_type are filled in. Defaults to true for backwards compatibility with APIV1 use of numbers endpoints.

call_recording_enabled
boolean

Indicates whether call recording is enabled for this number.

caller_id_name_enabled
boolean

Indicates whether caller ID is enabled for this number.

cnam_listing_enabled
boolean

Indicates whether a CNAM listing is enabled for this number.

connection_id
string

Identifies the connection associated with the phone number.

connection_name
string

The user-assigned name of the connection to be associated with this phone number.

created_at
string

ISO 8601 formatted date indicating when the resource was created.

customer_reference
string

A customer reference string for customer look ups.

emergency_address_id
string <int64>

Identifies the emergency address associated with the phone number.

emergency_enabled
boolean

Indicates whether emergency services are enabled for this number.

external_pin
string

If someone attempts to port your phone number away from Telnyx and your phone number has an external PIN set, Telnyx 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.

id
string <int64> (IntId)

Uniquely identifies the resource.

messaging_profile_id
string

Identifies the messaging profile associated with the phone number.

messaging_profile_name
string

The name of the messaging profile associated with the phone number.

number_level_routing
string
Default: "disabled"

Specifies whether the number can have overrides to the routing settings on itself (enabled) or if it uses the associated connection for all routing settings (disabled). Defaults to disabled or the value set on your user profile in default_number_routing_setting. There are performance advantages to using disabled and setting all routing information at the connection level.

Enum: "enabled" "disabled"
phone_number
string

The +E.164-formatted phone number associated with this record.

phone_number_type
string

The phone number's type.

Enum: "local" "toll_free" "mobile" "national" "shared_cost" "landline"
purchased_at
string

ISO 8601 formatted date indicating when the resource was purchased.

record_type
string

Identifies the type of the resource.

status
string

The phone number's current status.

Enum: "purchase-pending" "purchase-failed" "port-pending" "port-failed" "active" "deleted" "emergency-only" "ported-out" "port-out-pending"
t38_fax_gateway_enabled
boolean

Indicates whether T38 Fax Gateway for inbound calls to this number.

tags
Array of strings

A list of user-assigned tags to help manage the phone number.

default

Unexpected error

Response Schema: application/json
Array of objects (Error)
Array
code
required
string <int>
detail
string
meta
object
object
title
required
string
patch/phone_numbers/{id}
Request samples
application/json
{
  • "address_id": "dc8f39ac-953d-4520-b93b-786ae87db0da",
  • "billing_group_id": "dc8e4d67-33a0-4cbb-af74-7b58f05bd494",
  • "connection_id": "dc8e4d67-33a0-4cbb-af74-7b58f05bd494",
  • "customer_reference": "customer-reference",
  • "external_pin": "1234",
  • "id": "dc8e4d67-33a0-4cbb-af74-7b58f05bd494",
  • "number_level_routing": "disabled",
  • "tags": [
    • "tag"
    ]
}
Response samples
application/json
{
  • "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",
    • "number_level_routing": "disabled",
    • "phone_number": "+19705555098",
    • "phone_number_type": "local",
    • "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"
    }
}

Enable emergency for a phone number

SecuritybearerAuth
Request
path Parameters
id
required
string <int64>

Identifies the resource.

Example: 1293384261075731499
Request Body schema: application/json
required
emergency_address_id
required
string <int64>

Identifies the address to be used with emergency services.

emergency_enabled
required
boolean

Indicates whether to enable emergency services on this number.

Responses
200

Phone number emergency enabled.

Response Schema: application/json
object (PhoneNumberWithVoiceSettings)
object (CallForwarding)

The call forwarding settings for a phone number.

object (CallRecording)

The call recording settings for a phone number.

object (CnamListing)

The CNAM listing settings for a phone number.

connection_id
string

Identifies the connection associated with this phone number.

customer_reference
string

A customer reference string for customer look ups.

object (EmergencySettings)

The emergency services settings for a phone number.

id
string

Identifies the type of resource.

object (MediaFeatures)

The media features settings for a phone number.

phone_number
string

The phone number in +E164 format.

record_type
string

Identifies the type of the resource.

tech_prefix_enabled
boolean
Default: false

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

translated_number
string
Default: ""

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
Default: "pay-per-minute"

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

Enum: "pay-per-minute" "channel"
202

Phone number emergency requested.

Response Schema: application/json
object (PhoneNumberWithVoiceSettings)
object (CallForwarding)

The call forwarding settings for a phone number.

object (CallRecording)

The call recording settings for a phone number.

object (CnamListing)

The CNAM listing settings for a phone number.

connection_id
string

Identifies the connection associated with this phone number.

customer_reference
string

A customer reference string for customer look ups.

object (EmergencySettings)

The emergency services settings for a phone number.

id
string

Identifies the type of resource.

object (MediaFeatures)

The media features settings for a phone number.

phone_number
string

The phone number in +E164 format.

record_type
string

Identifies the type of the resource.

tech_prefix_enabled
boolean
Default: false

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

translated_number
string
Default: ""

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
Default: "pay-per-minute"

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

Enum: "pay-per-minute" "channel"
default

Unexpected error

Response Schema: application/json
Array of objects (Error)
Array
code
required
string <int>
detail
string
meta
object
object
title
required
string
post/phone_numbers/{id}/actions/enable_emergency
Request samples
application/json
{
  • "emergency_address_id": "53829456729313",
  • "emergency_enabled": true
}
Response samples
application/json
{
  • "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,
      • "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"
    }
}

Retrieve a phone number with messaging settings

SecuritybearerAuth
Request
path Parameters
id
required
string

Identifies the type of resource.

Responses
200

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

Response Schema: application/json
object (PhoneNumberWithMessagingSettings)
country_code
string^[A-Z]{2}$

ISO 3166-1 alpha-2 country code.

created_at
string <date-time>

ISO 8601 formatted date indicating when the resource was created.

eligible_messaging_products
Array of strings

The messaging products that this number can be registered to use

object
object (NumberHealthMetrics)

High level health metrics about the number and it's messaging sending patterns.

id
string

Identifies the type of resource.

messaging_product
string

The messaging product that the number is registered to use

messaging_profile_id
string

Unique identifier for a messaging profile.

phone_number
string <e164>

+E.164 formatted phone number.

record_type
string

Identifies the type of the resource.

Enum: "messaging_phone_number" "messaging_settings"
traffic_type
string

The messaging traffic or use case for which the number is currently configured.

type
string

The type of the phone number

Enum: "long-code" "toll-free" "short-code" "longcode" "tollfree" "shortcode"
updated_at
string <date-time>

ISO 8601 formatted date indicating when the resource was updated.

default

Unexpected error

Response Schema: application/json
Array of objects (Error)
Array
code
required
string <int>
detail
string
meta
object
object
title
required
string
get/phone_numbers/{id}/messaging
Request samples 
import telnyx
telnyx.api_key = "YOUR_API_KEY"

telnyx.MessagingPhoneNumber.retrieve("id")
Response samples
application/json
{
  • "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 settings

SecuritybearerAuth
Request
path Parameters
id
required
string

Identifies the type of resource.

Request Body schema: application/json
required

Updated messaging settings for the phone number

messaging_product
string

The requested messaging product the number should be on

messaging_profile_id
string

Unique identifier for a messaging profile.

Responses
200

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

Response Schema: application/json
object (PhoneNumberWithMessagingSettings)
country_code
string^[A-Z]{2}$

ISO 3166-1 alpha-2 country code.

created_at
string <date-time>

ISO 8601 formatted date indicating when the resource was created.

eligible_messaging_products
Array of strings

The messaging products that this number can be registered to use

object
object (NumberHealthMetrics)

High level health metrics about the number and it's messaging sending patterns.

id
string

Identifies the type of resource.

messaging_product
string

The messaging product that the number is registered to use

messaging_profile_id
string

Unique identifier for a messaging profile.

phone_number
string <e164>

+E.164 formatted phone number.

record_type
string

Identifies the type of the resource.

Enum: "messaging_phone_number" "messaging_settings"
traffic_type
string

The messaging traffic or use case for which the number is currently configured.

type
string

The type of the phone number

Enum: "long-code" "toll-free" "short-code" "longcode" "tollfree" "shortcode"
updated_at
string <date-time>

ISO 8601 formatted date indicating when the resource was updated.

default

Unexpected error

Response Schema: application/json
Array of objects (Error)
Array
code
required
string <int>
detail
string
meta
object
object
title
required
string
patch/phone_numbers/{id}/messaging
Request samples
application/json
{
  • "messaging_product": "P2P",
  • "messaging_profile_id": "dd50eba1-a0c0-4563-9925-b25e842a7cb6"
}
Response samples
application/json
{
  • "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"
    }
}

Retrieve a phone number with voice settings

SecuritybearerAuth
Request
path Parameters
id
required
string <int64>

Identifies the resource.

Example: 1293384261075731499
Responses
200

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

Response Schema: application/json
object (PhoneNumberWithVoiceSettings)
object (CallForwarding)

The call forwarding settings for a phone number.

object (CallRecording)

The call recording settings for a phone number.

object (CnamListing)

The CNAM listing settings for a phone number.

connection_id
string

Identifies the connection associated with this phone number.

customer_reference
string

A customer reference string for customer look ups.

object (EmergencySettings)

The emergency services settings for a phone number.

id
string

Identifies the type of resource.

object (MediaFeatures)

The media features settings for a phone number.

phone_number
string

The phone number in +E164 format.

record_type
string

Identifies the type of the resource.

tech_prefix_enabled
boolean
Default: false

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

translated_number
string
Default: ""

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
Default: "pay-per-minute"

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

Enum: "pay-per-minute" "channel"
default

Unexpected error

Response Schema: application/json
Array of objects (Error)
Array
code
required
string <int>
detail
string
meta
object
object
title
required
string
get/phone_numbers/{id}/voice
Request samples 
import telnyx
telnyx.api_key = "YOUR_API_KEY"

telnyx.PhoneNumbers.retrieve_voice.retrieve("id")
Response samples
application/json
{
  • "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,
      • "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 settings

SecuritybearerAuth
Request
path Parameters
id
required
string <int64>

Identifies the resource.

Example: 1293384261075731499
Request Body schema: application/json
required

Updated voice settings for the phone number.

object (CallForwarding)

The call forwarding settings for a phone number.

object (CallRecording)

The call recording settings for a phone number.

object (CnamListing)

The CNAM listing settings for a phone number.

object (MediaFeatures)

The media features settings for a phone number.

tech_prefix_enabled
boolean
Default: false

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

translated_number
string

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
Default: "pay-per-minute"

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

Enum: "pay-per-minute" "channel"
Responses
200

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

Response Schema: application/json
object (PhoneNumberWithVoiceSettings)
object (CallForwarding)

The call forwarding settings for a phone number.

object (CallRecording)

The call recording settings for a phone number.

object (CnamListing)

The CNAM listing settings for a phone number.

connection_id
string

Identifies the connection associated with this phone number.

customer_reference
string

A customer reference string for customer look ups.

object (EmergencySettings)

The emergency services settings for a phone number.

id
string

Identifies the type of resource.

object (MediaFeatures)

The media features settings for a phone number.

phone_number
string

The phone number in +E164 format.

record_type
string

Identifies the type of the resource.

tech_prefix_enabled
boolean
Default: false

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

translated_number
string
Default: ""

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
Default: "pay-per-minute"

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

Enum: "pay-per-minute" "channel"
default

Unexpected error

Response Schema: application/json
Array of objects (Error)
Array
code
required
string <int>
detail
string
meta
object
object
title
required
string
patch/phone_numbers/{id}/voice
Request samples
application/json
{
  • "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
    },
  • "media_features": {
    • "accept_any_rtp_packets_enabled": true,
    • "rtp_auto_adjust_enabled": true,
    • "t38_fax_gateway_enabled": true
    },
  • "tech_prefix_enabled": true,
  • "translated_number": "+13035559999",
  • "usage_payment_method": "pay-per-minute"
}
Response samples
application/json
{
  • "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,
      • "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"
    }
}