OpenAPI Specification
openapi: 3.1.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 Access Tokens Mobile Phone Numbers 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: Mobile phone number operations
name: Mobile Phone Numbers
paths:
/v2/mobile_phone_numbers:
get:
operationId: listMobilePhoneNumbers
parameters:
- description: The page number to load
in: query
name: page[number]
schema:
type: integer
- description: The size of the page
in: query
name: page[size]
schema:
type: integer
responses:
'200':
content:
application/json:
schema:
properties:
data:
items:
$ref: '#/components/schemas/MobilePhoneNumber'
type: array
meta:
$ref: '#/components/schemas/mobile_phone_numbers_PaginationMeta'
type: object
description: Successful response
'401':
description: Unauthorized
summary: List Mobile Phone Numbers
tags:
- Mobile Phone Numbers
x-latency-category: responsive
/v2/mobile_phone_numbers/{id}:
get:
operationId: retrieveMobilePhoneNumber
parameters:
- description: The ID of the mobile phone number
in: path
name: id
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
properties:
data:
$ref: '#/components/schemas/MobilePhoneNumber'
type: object
description: Successful response
'404':
description: Resource not found
summary: Retrieve a Mobile Phone Number
tags:
- Mobile Phone Numbers
x-latency-category: responsive
patch:
operationId: updateMobilePhoneNumber
parameters:
- description: The ID of the mobile phone number
in: path
name: id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/MobilePhoneNumberUpdate'
required: true
responses:
'200':
content:
application/json:
schema:
properties:
data:
$ref: '#/components/schemas/MobilePhoneNumber'
type: object
description: Successful response
'422':
description: Unprocessable Entity
summary: Update a Mobile Phone Number
tags:
- Mobile Phone Numbers
x-latency-category: responsive
components:
schemas:
MobilePhoneNumber:
properties:
call_forwarding:
properties:
call_forwarding_enabled:
type: boolean
forwarding_type:
enum:
- always
- on-failure
type:
- string
- 'null'
forwards_to:
type:
- string
- 'null'
type: object
call_recording:
properties:
inbound_call_recording_channels:
enum:
- single
- dual
type: string
inbound_call_recording_enabled:
type: boolean
inbound_call_recording_format:
enum:
- wav
- mp3
type: string
type: object
caller_id_name_enabled:
description: Indicates if caller ID name is enabled.
type: boolean
cnam_listing:
properties:
cnam_listing_details:
type:
- string
- 'null'
cnam_listing_enabled:
type: boolean
type: object
connection_id:
description: The ID of the connection associated with this number.
type:
- string
- 'null'
x-format: int64
connection_name:
description: The name of the connection.
readOnly: true
type:
- string
- 'null'
connection_type:
description: The type of the connection.
readOnly: true
type:
- string
- 'null'
country_iso_alpha2:
description: The ISO 3166-1 alpha-2 country code of the number.
readOnly: true
type: string
created_at:
description: ISO 8601 formatted date indicating when the resource was created.
format: date-time
readOnly: true
type: string
customer_reference:
description: A customer reference string.
type:
- string
- 'null'
id:
description: Identifies the resource.
readOnly: true
type: string
inbound:
properties:
interception_app_id:
description: The ID of the app that will intercept inbound calls.
type:
- string
- 'null'
x-format: int64
interception_app_name:
description: The name of the app that will intercept inbound calls.
readOnly: true
type:
- string
- 'null'
type: object
inbound_call_screening:
description: The inbound call screening setting.
enum:
- disabled
- reject_calls
- flag_calls
type:
- string
- 'null'
mobile_voice_enabled:
description: Indicates if mobile voice is enabled.
readOnly: true
type: boolean
noise_suppression:
description: The noise suppression setting.
enum:
- inbound
- outbound
- both
- disabled
type: string
outbound:
properties:
interception_app_id:
description: The ID of the app that will intercept outbound calls.
type:
- string
- 'null'
x-format: int64
interception_app_name:
description: The name of the app that will intercept outbound calls.
readOnly: true
type:
- string
- 'null'
type: object
phone_number:
description: The +E.164-formatted phone number.
readOnly: true
type: string
record_type:
description: Identifies the type of the resource.
example: mobile_phone_number
readOnly: true
type: string
sim_card_id:
description: The ID of the SIM card associated with this number.
format: uuid
readOnly: true
type: string
status:
description: The status of the phone number.
readOnly: true
type: string
tags:
description: A list of tags associated with the number.
items:
type: string
type: array
updated_at:
description: ISO 8601 formatted date indicating when the resource was last updated.
format: date-time
readOnly: true
type: string
type: object
MobilePhoneNumberUpdate:
properties:
call_forwarding:
properties:
call_forwarding_enabled:
type: boolean
forwarding_type:
enum:
- always
- on-failure
type:
- string
- 'null'
forwards_to:
type:
- string
- 'null'
type: object
call_recording:
properties:
inbound_call_recording_channels:
enum:
- single
- dual
type: string
inbound_call_recording_enabled:
type: boolean
inbound_call_recording_format:
enum:
- wav
- mp3
type: string
type: object
caller_id_name_enabled:
type: boolean
cnam_listing:
properties:
cnam_listing_details:
type:
- string
- 'null'
cnam_listing_enabled:
type: boolean
type: object
connection_id:
type:
- string
- 'null'
customer_reference:
type:
- string
- 'null'
inbound:
properties:
interception_app_id:
description: The ID of the CallControl or TeXML Application that will intercept inbound calls.
type:
- string
- 'null'
x-format: int64
type: object
inbound_call_screening:
enum:
- disabled
- reject_calls
- flag_calls
type: string
noise_suppression:
type: boolean
outbound:
properties:
interception_app_id:
description: The ID of the CallControl or TeXML Application that will intercept outbound calls.
type:
- string
- 'null'
x-format: int64
type: object
tags:
items:
type: string
type: array
type: object
mobile_phone_numbers_PaginationMeta:
properties:
page_number:
type: integer
page_size:
type: integer
total_pages:
type: integer
total_results:
type: integer
type: object
securitySchemes:
bearerAuth:
scheme: bearer
type: http
branded-calling_bearerAuth:
description: API key passed as a Bearer token in the Authorization header
scheme: bearer
type: http
oauthClientAuth:
description: OAuth 2.0 authentication for Telnyx API and MCP integrations
flows:
authorizationCode:
authorizationUrl: https://api.telnyx.com/v2/oauth/authorize
refreshUrl: https://api.telnyx.com/v2/oauth/token
scopes:
admin: Administrative access to Telnyx resources
tokenUrl: https://api.telnyx.com/v2/oauth/token
clientCredentials:
scopes:
admin: Administrative access to Telnyx resources
tokenUrl: https://api.telnyx.com/v2/oauth/token
type: oauth2
outbound-voice-profiles_bearerAuth:
bearerFormat: JWT
scheme: bearer
type: http
pronunciation-dicts_bearerAuth:
description: Telnyx API v2 key. Obtain from https://portal.telnyx.com
scheme: bearer
type: http
stored-payment-transactions_bearerAuth:
bearerFormat: JWT
scheme: bearer
type: http