Telnyx Phone Number Configurations API
Configure your phone numbers
Configure your phone numbers
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/telnyx-phone-number-configurations-api"
curl "https://apis.io/api/v1/apis?limit=25"
Discovery needs no key. Ratings and market analysis are Pro.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
contact:
email: support@telnyx.com
description: Telnyx provides global communications and connectivity APIs for developers — including SIP trunking, programmable voice, SMS, MMS, WhatsApp Business Messaging, Call Control, Fax, Wireless (IoT & eSIM), Phone Numbers (DID provisioning & porting), Emergency Services, and Network APIs for private interconnects and edge connectivity. Build, scale, and manage voice, messaging, and data networks with Telnyx's carrier-grade global infrastructure and API-first platform.
title: Telnyx Phone Number Configurations API
version: 2.0.0
x-endpoint-cost: light
servers:
- description: Version 2.0.0 of the Telnyx API
url: https://api.telnyx.com/v2
security:
- bearerAuth: []
tags:
- description: Configure your phone numbers
name: Phone Number Configurations
paths:
/phone_numbers:
get:
operationId: ListPhoneNumbers
parameters:
- $ref: '#/components/parameters/numbers_PageConsolidated'
- description: Specifies the sort order for results. If not given, results are sorted by created_at in descending order.
in: query
name: sort
required: false
schema:
enum:
- purchased_at
- phone_number
- connection_name
- usage_payment_method
example: connection_name
type: string
- description: 'Consolidated filter parameter (deepObject style). Originally: filter[tag], filter[phone_number], filter[status], filter[country_iso_alpha2], filter[connection_id], filter[voice.connection_name], filter[voice.usage_payment_method], filter[billing_group_id], filter[emergency_address_id], filter[customer_reference], filter[number_type], filter[source]'
explode: true
in: query
name: filter
schema:
properties:
billing_group_id:
description: 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
type: string
connection_id:
description: Filter by connection_id.
example: '1521916448077776306'
type: string
country_iso_alpha2:
description: Filter by phone number country ISO alpha-2 code. Can be a single value or an array of values.
oneOf:
- example: US
type: string
- example:
- US
- CA
items:
type: string
type: array
customer_reference:
description: Filter numbers via the customer_reference set.
type: string
emergency_address_id:
description: 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'
type: string
number_type:
additionalProperties: false
description: Filter phone numbers by phone number type.
properties:
eq:
description: Filter phone numbers by phone number type.
enum:
- local
- national
- toll_free
- mobile
- shared_cost
type: string
type: object
phone_number:
description: "Filter by phone number. Requires at least three digits.\n Non-numerical characters will result in no values being returned."
type: string
source:
description: Filter phone numbers by their source. Use 'ported' for numbers ported from other carriers, or 'purchased' for numbers bought directly from Telnyx.
enum:
- ported
- purchased
type: string
status:
description: Filter by phone number status.
enum:
- purchase-pending
- purchase-failed
- port-pending
- active
- deleted
- port-failed
- emergency-only
- ported-out
- port-out-pending
example: active
type: string
tag:
description: Filter by phone number tags.
type: string
voice.connection_name:
additionalProperties: false
description: Filter by voice connection name pattern matching.
properties:
contains:
description: Filter contains connection name. Requires at least three characters.
example: test
type: string
ends_with:
description: Filter ends with connection name. Requires at least three characters.
example: test
type: string
eq:
description: Filter by connection name.
example: test
type: string
starts_with:
description: Filter starts with connection name. Requires at least three characters.
example: test
type: string
type: object
voice.usage_payment_method:
description: Filter by usage_payment_method.
enum:
- pay-per-minute
- channel
example: channel
type: string
without_tags:
description: When set to 'true', filters for phone numbers that do not have any tags applied. All other values are ignored.
enum:
- 'true'
- 'false'
type: string
type: object
style: deepObject
- description: Although it is an infrequent occurrence, due to the highly distributed nature of the Telnyx platform, it is possible that there will be an issue when loading in Messaging Profile information. As such, when this parameter is set to `true` and an error in fetching this information occurs, messaging profile related fields will be omitted in the response and an error message will be included instead of returning a 503 error.
in: query
name: handle_messaging_profile_error
schema:
default: 'false'
enum:
- 'true'
- 'false'
example: 'false'
type: string
responses:
'200':
$ref: '#/components/responses/ListPhoneNumbersResponse'
'400':
$ref: '#/components/responses/numbers_BadRequestResponse'
'401':
$ref: '#/components/responses/numbers_UnauthorizedResponse'
'404':
$ref: '#/components/responses/numbers_NotFoundResponse'
'422':
$ref: '#/components/responses/numbers_UnprocessableEntity'
'500':
$ref: '#/components/responses/numbers_GenericErrorResponse'
summary: List phone numbers
tags:
- Phone Number Configurations
x-endpoint-cost: medium
x-group-parameters: 'true'
x-latency-category: responsive
/phone_numbers/actions/verify_ownership:
post:
description: Verifies ownership of the provided phone numbers and returns a mapping of numbers to their IDs, plus a list of numbers not found in the account.
operationId: VerifyPhoneNumberOwnership
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PhoneNumberVerifyOwnershipRequest'
required: true
responses:
'200':
content:
application/json:
schema:
properties:
data:
$ref: '#/components/schemas/PhoneNumberVerifyOwnershipResponse'
title: Phone Number Verify Ownership Response
type: object
description: Phone number ownership verification completed.
'400':
$ref: '#/components/responses/numbers_BadRequestResponse'
'401':
$ref: '#/components/responses/numbers_UnauthorizedResponse'
'404':
$ref: '#/components/responses/numbers_NotFoundResponse'
'422':
$ref: '#/components/responses/numbers_UnprocessableEntity'
'500':
$ref: '#/components/responses/numbers_GenericErrorResponse'
summary: Verify ownership of phone numbers
tags:
- Phone Number Configurations
x-endpoint-cost: light
x-latency-category: responsive
/phone_numbers/slim:
get:
description: List phone numbers, This endpoint is a lighter version of the /phone_numbers endpoint having higher performance and rate limit.
operationId: SlimListPhoneNumbers
parameters:
- $ref: '#/components/parameters/numbers_PageConsolidated'
- description: Include the connection associated with the phone number.
in: query
name: include_connection
required: false
schema:
default: false
type: boolean
- description: Include the tags associated with the phone number.
in: query
name: include_tags
required: false
schema:
default: false
type: boolean
- description: Specifies the sort order for results. If not given, results are sorted by created_at in descending order.
in: query
name: sort
required: false
schema:
enum:
- purchased_at
- phone_number
- connection_name
- usage_payment_method
example: connection_name
type: string
- description: 'Consolidated filter parameter (deepObject style). Originally: filter[tag], filter[phone_number], filter[status], filter[country_iso_alpha2], filter[connection_id], filter[voice.connection_name], filter[voice.usage_payment_method], filter[billing_group_id], filter[emergency_address_id], filter[customer_reference], filter[number_type], filter[source]'
explode: true
in: query
name: filter
schema:
properties:
billing_group_id:
description: 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
type: string
connection_id:
description: Filter by connection_id.
example: '1521916448077776306'
type: string
country_iso_alpha2:
description: Filter by phone number country ISO alpha-2 code. Can be a single value or an array of values.
oneOf:
- example: US
type: string
- example:
- US
- CA
items:
type: string
type: array
customer_reference:
description: Filter numbers via the customer_reference set.
type: string
emergency_address_id:
description: 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'
type: string
number_type:
additionalProperties: false
description: Filter phone numbers by phone number type.
properties:
eq:
description: Filter phone numbers by phone number type.
enum:
- local
- national
- toll_free
- mobile
- shared_cost
type: string
type: object
phone_number:
description: "Filter by phone number. Requires at least three digits.\n Non-numerical characters will result in no values being returned."
type: string
source:
description: Filter phone numbers by their source. Use 'ported' for numbers ported from other carriers, or 'purchased' for numbers bought directly from Telnyx.
enum:
- ported
- purchased
type: string
status:
description: Filter by phone number status.
enum:
- purchase-pending
- purchase-failed
- port_pending
- active
- deleted
- port-failed
- emergency-only
- ported-out
- port-out-pending
example: active
type: string
tag:
description: Filter by phone number tags. (This requires the include_tags param)
type: string
voice.connection_name:
additionalProperties: false
description: Filter by voice connection name pattern matching (requires include_connection param).
properties:
contains:
description: Filter contains connection name. Requires at least three characters and the include_connection param.
example: test
type: string
ends_with:
description: Filter ends with connection name. Requires at least three characters and the include_connection param.
example: test
type: string
eq:
description: Filter by connection name.
example: test
type: string
starts_with:
description: Filter starts with connection name. Requires at least three characters and the include_connection param.
example: test
type: string
type: object
voice.usage_payment_method:
description: Filter by usage_payment_method.
enum:
- pay-per-minute
- channel
example: channel
type: string
type: object
style: deepObject
responses:
'200':
$ref: '#/components/responses/SlimListPhoneNumbersResponse'
'400':
$ref: '#/components/responses/numbers_BadRequestResponse'
'401':
$ref: '#/components/responses/numbers_UnauthorizedResponse'
'404':
$ref: '#/components/responses/numbers_NotFoundResponse'
'422':
$ref: '#/components/responses/numbers_UnprocessableEntity'
'500':
$ref: '#/components/responses/numbers_GenericErrorResponse'
summary: Slim List phone numbers
tags:
- Phone Number Configurations
x-endpoint-cost: medium
x-group-parameters: 'true'
x-latency-category: responsive
/phone_numbers/voice:
get:
operationId: ListPhoneNumbersWithVoiceSettings
parameters:
- $ref: '#/components/parameters/numbers_PageConsolidated'
- description: Specifies the sort order for results. If not given, results are sorted by created_at in descending order.
in: query
name: sort
required: false
schema:
enum:
- purchased_at
- phone_number
- connection_name
- usage_payment_method
example: connection_name
type: string
- description: 'Consolidated filter parameter (deepObject style). Originally: filter[phone_number], filter[connection_name], filter[customer_reference], filter[voice.usage_payment_method]'
explode: true
in: query
name: filter
schema:
properties:
connection_name:
additionalProperties: false
description: Filter by connection name pattern matching.
properties:
contains:
description: Filter contains connection name. Requires at least three characters.
example: test
type: string
type: object
customer_reference:
description: Filter numbers via the customer_reference set.
type: string
phone_number:
description: "Filter by phone number. Requires at least three digits.\n Non-numerical characters will result in no values being returned."
type: string
voice.usage_payment_method:
description: Filter by usage_payment_method.
enum:
- pay-per-minute
- channel
example: channel
type: string
type: object
style: deepObject
responses:
'200':
$ref: '#/components/responses/ListPhoneNumbersWithVoiceSettingsResponse'
'400':
$ref: '#/components/responses/numbers_BadRequestResponse'
'401':
$ref: '#/components/responses/numbers_UnauthorizedResponse'
'404':
$ref: '#/components/responses/numbers_NotFoundResponse'
'422':
$ref: '#/components/responses/numbers_UnprocessableEntity'
'500':
$ref: '#/components/responses/numbers_GenericErrorResponse'
summary: List phone numbers with voice settings
tags:
- Phone Number Configurations
x-endpoint-cost: medium
x-group-parameters: 'true'
x-latency-category: responsive
/phone_numbers/{id}:
delete:
operationId: DeletePhoneNumber
parameters:
- $ref: '#/components/parameters/IntId'
responses:
'200':
$ref: '#/components/responses/DeletePhoneNumberResponse'
'400':
$ref: '#/components/responses/numbers_BadRequestResponse'
'401':
$ref: '#/components/responses/numbers_UnauthorizedResponse'
'404':
$ref: '#/components/responses/numbers_NotFoundResponse'
'422':
$ref: '#/components/responses/numbers_UnprocessableEntity'
'500':
$ref: '#/components/responses/numbers_GenericErrorResponse'
summary: Delete a phone number
tags:
- Phone Number Configurations
x-endpoint-cost: medium
x-latency-category: responsive
get:
operationId: RetrievePhoneNumber
parameters:
- $ref: '#/components/parameters/IntId'
responses:
'200':
$ref: '#/components/responses/PhoneNumberResponse'
'400':
$ref: '#/components/responses/numbers_BadRequestResponse'
'401':
$ref: '#/components/responses/numbers_UnauthorizedResponse'
'404':
$ref: '#/components/responses/numbers_NotFoundResponse'
'422':
$ref: '#/components/responses/numbers_UnprocessableEntity'
'500':
$ref: '#/components/responses/numbers_GenericErrorResponse'
summary: Retrieve a phone number
tags:
- Phone Number Configurations
x-endpoint-cost: medium
x-latency-category: responsive
patch:
operationId: UpdatePhoneNumber
parameters:
- $ref: '#/components/parameters/IntId'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UpdatePhoneNumberRequest'
description: Updated settings for the phone number.
required: true
responses:
'200':
$ref: '#/components/responses/PhoneNumberResponse'
'400':
$ref: '#/components/responses/numbers_BadRequestResponse'
'401':
$ref: '#/components/responses/numbers_UnauthorizedResponse'
'404':
$ref: '#/components/responses/numbers_NotFoundResponse'
'422':
$ref: '#/components/responses/numbers_UnprocessableEntity'
'500':
$ref: '#/components/responses/numbers_GenericErrorResponse'
summary: Update a phone number
tags:
- Phone Number Configurations
x-endpoint-cost: medium
x-latency-category: responsive
/phone_numbers/{id}/actions/bundle_status_change:
patch:
operationId: PhoneNumberBundleStatusChange
parameters:
- $ref: '#/components/parameters/IntId'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PhoneNumberBundleStatusChangeRequest'
required: true
responses:
'200':
content:
application/json:
schema:
properties:
data:
$ref: '#/components/schemas/PhoneNumberWithVoiceSettings'
title: Phone Number Bundle Status Change
type: object
description: Phone number bundle status change success
'400':
$ref: '#/components/responses/numbers_BadRequestResponse'
'401':
$ref: '#/components/responses/numbers_UnauthorizedResponse'
'404':
$ref: '#/components/responses/numbers_NotFoundResponse'
'422':
$ref: '#/components/responses/numbers_UnprocessableEntity'
'500':
$ref: '#/components/responses/numbers_GenericErrorResponse'
summary: Change the bundle status for a phone number (set to being in a bundle or remove from a bundle)
tags:
- Phone Number Configurations
x-endpoint-cost: medium
x-latency-category: responsive
/phone_numbers/{id}/actions/enable_emergency:
post:
operationId: EnablePhoneNumberEmergency
parameters:
- $ref: '#/components/parameters/IntId'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PhoneNumberEnableEmergencyRequest'
required: true
responses:
'200':
content:
application/json:
schema:
properties:
data:
$ref: '#/components/schemas/PhoneNumberWithVoiceSettings'
title: Phone Number Enable Emergency
type: object
description: Phone number emergency enabled.
'202':
content:
application/json:
schema:
properties:
data:
$ref: '#/components/schemas/PhoneNumberWithVoiceSettings'
title: Phone Number Enable Emergency
type: object
description: Phone number emergency requested.
'400':
$ref: '#/components/responses/numbers_BadRequestResponse'
'401':
$ref: '#/components/responses/numbers_UnauthorizedResponse'
'404':
$ref: '#/components/responses/numbers_NotFoundResponse'
'422':
$ref: '#/components/responses/numbers_UnprocessableEntity'
'500':
$ref: '#/components/responses/numbers_GenericErrorResponse'
summary: Enable emergency for a phone number
tags:
- Phone Number Configurations
x-endpoint-cost: medium
x-latency-category: responsive
/phone_numbers/{id}/voice:
get:
operationId: GetPhoneNumberVoiceSettings
parameters:
- $ref: '#/components/parameters/IntId'
responses:
'200':
$ref: '#/components/responses/PhoneNumberWithVoiceSettingsResponse'
'400':
$ref: '#/components/responses/numbers_BadRequestResponse'
'401':
$ref: '#/components/responses/numbers_UnauthorizedResponse'
'404':
$ref: '#/components/responses/numbers_NotFoundResponse'
'422':
$ref: '#/components/responses/numbers_UnprocessableEntity'
'500':
$ref: '#/components/responses/numbers_GenericErrorResponse'
summary: Retrieve a phone number with voice settings
tags:
- Phone Number Configurations
x-endpoint-cost: medium
x-latency-category: responsive
patch:
operationId: UpdatePhoneNumberVoiceSettings
parameters:
- $ref: '#/components/parameters/IntId'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UpdatePhoneNumberVoiceSettingsRequest'
description: Updated voice settings for the phone number.
required: true
responses:
'200':
$ref: '#/components/responses/PhoneNumberWithVoiceSettingsResponse'
'400':
$ref: '#/components/responses/numbers_BadRequestResponse'
'401':
$ref: '#/components/responses/numbers_UnauthorizedResponse'
'404':
$ref: '#/components/responses/numbers_NotFoundResponse'
'422':
$ref: '#/components/responses/numbers_UnprocessableEntity'
'500':
$ref: '#/components/responses/numbers_GenericErrorResponse'
summary: Update a phone number with voice settings
tags:
- Phone Number Configurations
x-endpoint-cost: medium
x-latency-category: responsive
components:
responses:
PhoneNumberWithVoiceSettingsResponse:
content:
application/json:
schema:
properties:
data:
$ref: '#/components/schemas/PhoneNumberWithVoiceSettings'
title: Retrieve Phone Number Voice Response
type: object
description: Successful response with details about a phone number including voice settings.
numbers_BadRequestResponse:
content:
application/json:
schema:
$ref: '#/components/schemas/numbers_Errors'
description: Bad request, the request was unacceptable, often due to missing a required parameter.
PhoneNumberResponse:
content:
application/json:
schema:
properties:
data:
$ref: '#/components/schemas/PhoneNumberDetailed'
title: Phone Number Response
type: object
description: Successful response with details about a phone number.
DeletePhoneNumberResponse:
content:
application/json:
schema:
properties:
data:
$ref: '#/components/schemas/PhoneNumberDeletedDetailed'
title: Phone Number Response
type: object
description: Successful response with details about a phone number.
numbers_NotFoundResponse:
content:
application/json:
schema:
$ref: '#/components/schemas/numbers_Errors'
description: The requested resource doesn't exist.
numbers_UnauthorizedResponse:
content:
application/json:
examples:
Authentication Failed:
value:
errors:
- code: '10009'
detail: Could not understand the provided credentials.
meta:
url: https://developers.telnyx.com/docs/overview/errors/10009
title: Authentication failed
schema:
$ref: '#/components/schemas/numbers_Errors'
description: Unauthorized
SlimListPhoneNumbersResponse:
content:
application/json:
schema:
properties:
data:
items:
$ref: '#/components/schemas/SlimPhoneNumberDetailed'
type: array
meta:
$ref: '#/components/schemas/PaginationMeta'
title: List Phone Numbers Response
type: object
description: Successful response with a list of phone numbers.
numbers_GenericErrorResponse:
content:
application/json:
schema:
$ref: '#/components/schemas/numbers_Errors'
description: Unexpected error
numbers_UnprocessableEntity:
content:
application/json:
schema:
$ref: '#/components/schemas/numbers_Errors'
description: Unprocessable entity. Check the 'detail' field in response for details.
ListPhoneNumbersWithVoiceSettingsResponse:
content:
application/json:
schema:
properties:
data:
items:
$ref: '#/components/schemas/PhoneNumberWithVoiceSettings'
type: array
meta:
$ref: '#/components/schemas/PaginationMeta'
title: List Phone Numbers With Voice Settings Response
type: object
description: Successful response with a list of phone numbers with voice settings.
ListPhoneNumbersResponse:
content:
application/json:
schema:
properties:
data:
items:
$ref: '#/components/schemas/PhoneNumberDetailed'
type: array
errors:
items:
$ref: '#/components/schemas/numbers_Error'
type: array
meta:
$ref: '#/components/schemas/PaginationMeta'
required:
- data
- meta
title: List Phone Numbers Response
type: object
description: Successful response with a list of phone numbers.
schemas:
PhoneNumberWithVoiceSettings:
example:
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
emergency_status: active
id: '1293384261075731499'
inbound_call_screening: disabled
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
properties:
call_forwarding:
$ref: '#/components/schemas/CallForwarding'
call_recording:
$ref: '#/components/schemas/CallRecording'
cnam_listing:
$ref: '#/components/schemas/CnamListing'
connection_id:
description: Identifies the connection associated with this phone number.
example: 1d0e6cb8-8668-462e-94c6-49ae0f0ed48b
type: string
customer_reference:
description: A customer reference string for customer look ups.
example: MY REF 001
type: string
emergency:
$ref: '#/components/schemas/EmergencySettings'
id:
description: Identifies the type of resource.
example: '1293384261075731499'
readOnly: true
type: string
inbound_call_screening:
default: disabled
description: 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.
enum:
- disabled
- reject_calls
- flag_calls
type: string
media_features:
$ref: '#/components/schemas/MediaFeatures'
phone_number:
description: The phone number in +E164 format.
example: '+13035551234'
readOnly: true
type: string
record_type:
description: Identifies the type of the resource.
example: voice_settings
readOnly: true
type: string
tech_prefix_enabled:
default: false
description: Controls whether a tech prefix is enabled for this phone number.
# --- truncated at 32 KB (66 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/telnyx/refs/heads/main/openapi/telnyx-phone-number-configurations-api-openapi.yml