Update a phone number

curl --location --request PATCH '/phone_numbers/' \ --header 'Content-Type: application/json' \ --data-raw '{ "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", "hd_voice_enabled": true, "id": "dc8e4d67-33a0-4cbb-af74-7b58f05bd494", "tags": [ "tag" ] }'

{ "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", "country_iso_alpha2": "US", "created_at": "2019-10-23T18:10:00.000Z", "customer_reference": "customer-reference", "emergency_address_id": "1315261609962112019", "emergency_enabled": true, "emergency_status": "active", "external_pin": "1234", "hd_voice_enabled": true, "id": "1293384261075731499", "inbound_call_screening": "disabled", "messaging_profile_id": "abc85f64-5717-4562-b3fc-2c9600000000", "messaging_profile_name": "regional-customers", "phone_number": "+19705555098", "phone_number_type": "local", "purchased_at": "2019-10-23T18:10:00.000Z", "record_type": "phone_number", "source_type": "number_order", "status": "active", "t38_fax_gateway_enabled": true, "tags": [ "tag_1", "tag_2" ], "updated_at": "2019-10-24T18:10:00.000Z" } }

Request

Authorization

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

Authorization: Bearer ********************

Path Params

string <int64>

required

Identifies the resource.

Example:

1293384261075731499

Body Params 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.

hd_voice_enabled

boolean

optional

Indicates whether HD voice is enabled for this number.

Example:

true

tags

array[string]

optional

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

Examples

Responses

🟢200OK

application/json

Successful response with details about a phone number.

Body

data

object (PhoneNumberDetailed)

optional

Example:

{"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","country_iso_alpha2":"US","created_at":"2019-10-23T18:10:00.000Z","customer_reference":"customer-reference","emergency_address_id":"1315261609962112019","emergency_enabled":true,"emergency_status":"active","external_pin":"1234","hd_voice_enabled":true,"id":"1293384261075731499","inbound_call_screening":"disabled","messaging_profile_id":"abc85f64-5717-4562-b3fc-2c9600000000","messaging_profile_name":"regional-customers","phone_number":"+19705555098","phone_number_type":"local","purchased_at":"2019-10-23T18:10:00.000Z","record_type":"phone_number","source_type":"number_order","status":"active","t38_fax_gateway_enabled":true,"tags":["tag_1","tag_2"],"updated_at":"2019-10-24T18:10:00.000Z"}

billing_group_id

string

optional

Identifies the billing group associated with the phone number.

call_forwarding_enabled

boolean

read-onlyoptional

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.

Default:

true

call_recording_enabled

boolean

read-onlyoptional

Indicates whether call recording is enabled for this number.

caller_id_name_enabled

boolean

read-onlyoptional

Indicates whether caller ID is enabled for this number.

cnam_listing_enabled

boolean

read-onlyoptional

Indicates whether a CNAM listing is enabled for this number.

connection_id

string

optional

Identifies the connection associated with the phone number.

connection_name

string

read-onlyoptional

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

country_iso_alpha2

string

read-onlyoptional

The ISO 3166-1 alpha-2 country code of the phone number.

Example:

created_at

string

read-onlyoptional

ISO 8601 formatted date indicating when the resource was created.

customer_reference

string

optional

A customer reference string for customer look ups.

Example:

MY REF 001

emergency_address_id

string <int64>

read-onlyoptional

Identifies the emergency address associated with the phone number.

emergency_enabled

boolean

read-onlyoptional

Indicates whether emergency services are enabled for this number.

emergency_status

enum<string>

optional

Indicates the status of the provisioning of emergency services for the phone number. This field contains information about activity that may be ongoing for a number where it either is being provisioned or deprovisioned but is not yet enabled/disabled.

Allowed values:

activedeprovisioningdisabledprovisioningprovisioning-failed

external_pin

string

optional

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.

string <int64>

optional

Uniquely identifies the resource.

Example:

1293384261075731499

inbound_call_screening

enum<string>

optional

The inbound_call_screening setting is a phone number configuration option variable that allows users to configure their settings to block or flag fraudulent calls. It can be set to disabled, reject_calls, or flag_calls. This feature has an additional per-number monthly cost associated with it.

Allowed values:

disabledreject_callsflag_calls

Default:

disabled

messaging_profile_id

string

optional

Identifies the messaging profile associated with the phone number.

messaging_profile_name

string

optional

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

Example:

regional-customers

phone_number

string

read-onlyoptional

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

phone_number_type

enum<string>

read-onlyoptional

The phone number's type.
Note: For numbers purchased prior to July 2023 or when fetching a number's details immediately after a purchase completes, the legacy values tollfree, shortcode or longcode may be returned instead.

Allowed values:

localtoll_freemobilenationalshared_costlandlinetollfreeshortcodelongcode

purchased_at

string

read-onlyoptional

ISO 8601 formatted date indicating when the resource was purchased.

record_type

string

read-onlyoptional

Identifies the type of the resource.

Example:

phone_number

source_type

enum<string> | enum<null>

read-onlyoptional

Indicates if the phone number was purchased or ported in. For some numbers this information may not be available.

Allowed values:

number_orderport_request

status

enum<string>

read-onlyoptional

The phone number's current status.

Allowed values:

purchase-pendingpurchase-failedport-pendingport-failedactivedeletedemergency-onlyported-outport-out-pendingrequirement-info-pendingrequirement-info-under-reviewrequirement-info-exceptionprovision-pending

t38_fax_gateway_enabled

boolean

read-onlyoptional

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