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 Voice Channels 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: Voice Channels
name: Voice Channels
paths:
/channel_zones:
get:
description: Returns the non-US voice channels for your account. voice channels allow you to use Channel Billing for calls to your Telnyx phone numbers. Please check the <a href="https://support.telnyx.com/en/articles/8428806-global-channel-billing">Telnyx Support Articles</a> section for full information and examples of how to utilize Channel Billing.
operationId: GetChannelZones
parameters:
- $ref: '#/components/parameters/voice-channels_PageConsolidated'
responses:
'200':
$ref: '#/components/responses/GetGcbChannelZonesRequestResponse'
'400':
description: Bad request
'401':
description: Unauthorized
'404':
description: Resource not found
summary: List your voice channels for non-US zones
tags:
- Voice Channels
x-latency-category: interactive
/channel_zones/{channel_zone_id}:
parameters:
- $ref: '#/components/parameters/GcbChannelZoneId'
put:
description: Update the number of Voice Channels for the Non-US Zones. This allows your account to handle multiple simultaneous inbound calls to Non-US numbers. Use this endpoint to increase or decrease your capacity based on expected call volume.
operationId: PatchChannelZone
requestBody:
content:
application/json:
schema:
properties:
channels:
description: The number of reserved channels
format: int64
type: integer
required:
- channels
type: object
description: Quantity of reserved channels and organizational update option
required: true
responses:
'200':
$ref: '#/components/responses/PatchGcbChannelZoneRequestResponse'
'400':
description: Bad request
'401':
description: Unauthorized
'404':
description: Resource not found
default:
$ref: '#/components/responses/voice-channels_GenericErrorResponse'
summary: Update voice channels for non-US Zones
tags:
- Voice Channels
x-codegen-request-body-name: body
x-latency-category: interactive
/inbound_channels:
get:
description: Returns the US Zone voice channels for your account. voice channels allows you to use Channel Billing for calls to your Telnyx phone numbers. Please check the <a href="https://support.telnyx.com/en/articles/8428806-global-channel-billing">Telnyx Support Articles</a> section for full information and examples of how to utilize Channel Billing.
operationId: ListInboundChannels
responses:
'200':
content:
application/json:
schema:
properties:
data:
properties:
channels:
description: The current number of concurrent channels set for the account
example: 7
type: integer
record_type:
description: Identifies the type of the response
example: inbound_channels
type: string
type: object
type: object
description: voice channels Response
'401':
description: Unauthorized
'404':
description: Resource not found
'422':
description: Unprocessable entity. Check message field in response for details.
summary: List your voice channels for US Zone
tags:
- Voice Channels
x-endpoint-cost: medium
x-latency-category: interactive
patch:
description: Update the number of Voice Channels for the US Zone. This allows your account to handle multiple simultaneous inbound calls to US numbers. Use this endpoint to increase or decrease your capacity based on expected call volume.
operationId: UpdateOutboundChannels
requestBody:
content:
application/json:
schema:
properties:
channels:
description: The new number of concurrent channels for the account
example: 7
type: integer
required:
- channels
type: object
description: Voice channels update
required: true
responses:
'200':
content:
application/json:
schema:
properties:
data:
properties:
channels:
description: The number of channels set for the account
example: 7
type: integer
record_type:
description: Identifies the type of the response
example: inbound_channels
type: string
type: object
type: object
description: Expected Update response
'400':
description: Bad request
'401':
description: Unauthorized
'404':
description: Resource not found
default:
content:
application/json:
schema:
properties:
errors:
items:
properties:
code:
type: string
detail:
type: string
meta:
type: object
source:
properties:
parameter:
description: Indicates which query parameter caused the error.
type: string
pointer:
description: JSON pointer (RFC6901) to the offending entity.
type: string
type: object
title:
type: string
required:
- code
- title
type: array
description: Unexpected error
summary: Update voice channels for US Zone
tags:
- Voice Channels
x-endpoint-cost: medium
x-latency-category: interactive
/list:
get:
description: Retrieve a list of all phone numbers using Channel Billing, grouped by Zone.
operationId: GetAllNumbersChannelZones
responses:
'200':
$ref: '#/components/responses/GetGcbNumbersResponse'
'400':
description: Bad request
'401':
description: Unauthorized
'404':
description: Resource not found
summary: List All Numbers using Channel Billing
tags:
- Voice Channels
x-latency-category: interactive
/list/{channel_zone_id}:
get:
description: Retrieve a list of phone numbers using Channel Billing for a specific Zone.
operationId: GetNumbersChannelZones
parameters:
- $ref: '#/components/parameters/GcbChannelNumberZoneId'
responses:
'200':
$ref: '#/components/responses/GetGcbNumbersResponse'
'400':
description: Bad request
'401':
description: Unauthorized
'404':
description: Resource not found
summary: List Numbers using Channel Billing for a specific Zone
tags:
- Voice Channels
x-latency-category: interactive
components:
parameters:
GcbChannelNumberZoneId:
description: Channel zone identifier
in: path
name: channel_zone_id
required: true
schema:
type: string
GcbChannelZoneId:
description: Channel zone identifier
in: path
name: channel_zone_id
required: true
schema:
type: string
voice-channels_PageConsolidated:
description: 'Consolidated page parameter (deepObject style). Originally: page[size], page[number]'
explode: true
in: query
name: page
schema:
properties:
number:
default: 1
description: The page number to load
minimum: 1
type: integer
size:
default: 20
description: The size of the page
maximum: 250
minimum: 1
type: integer
type: object
style: deepObject
responses:
GetGcbNumbersResponse:
content:
application/json:
schema:
properties:
data:
items:
properties:
number_of_channels:
example: 7
type: integer
numbers:
items:
properties:
country:
example: FR
type: string
number:
example: '+15554441234'
type: string
type: object
type: array
zone_id:
example: 1653e6a1-4bfd-4857-97c6-6a51e1c34477
type: string
zone_name:
example: Euro channel zone
type: string
type: object
type: array
meta:
$ref: '#/components/schemas/PaginationMeta'
type: object
description: A list of numbers using GCB, grouped by channel zone
GetGcbChannelZonesRequestResponse:
content:
application/json:
schema:
properties:
data:
items:
$ref: '#/components/schemas/GcbChannelZone'
type: array
meta:
$ref: '#/components/schemas/PaginationMeta'
type: object
description: A list of channel zones
PatchGcbChannelZoneRequestResponse:
content:
application/json:
schema:
$ref: '#/components/schemas/GcbChannelZone'
description: Successfuly patched channel zone
voice-channels_GenericErrorResponse:
content:
application/json:
schema:
$ref: '#/components/schemas/voice-channels_Errors'
description: Unexpected error
schemas:
PaginationMeta:
properties:
page_number:
example: 2
type: integer
page_size:
example: 25
type: integer
total_pages:
example: 3
type: integer
total_results:
example: 55
type: integer
type: object
voice-channels_Errors:
properties:
errors:
items:
$ref: '#/components/schemas/voice-channels_Error'
type: array
type: object
voice-channels_Error:
properties:
code:
type: string
detail:
type: string
meta:
additionalProperties: true
type: object
source:
properties:
parameter:
description: Indicates which query parameter caused the error.
type: string
pointer:
description: JSON pointer (RFC6901) to the offending entity.
type: string
type: object
title:
type: string
required:
- code
- title
type: object
GcbChannelZone:
properties:
channels:
example: 7
format: int64
type: integer
countries:
description: List of countries (in ISO 3166-2, capitalized) members of the billing channel zone
example:
- BE
- EL
- LT
- PT
- BG
- ES
- LU
- RO
- CZ
- FR
- HU
- SI
- DK
- HR
- MT
- SK
- DE
- IT
- NL
- FI
- EE
- CY
- AT
- SE
- IE
- LV
- PL
items:
type: string
type: array
created_at:
description: ISO 8601 formatted date of when the channel zone was created
example: '2019-01-23T18:10:02.574Z'
type: string
id:
example: 1653e6a1-4bfd-4857-97c6-6a51e1c34477
type: string
name:
example: Euro channel zone
type: string
record_type:
enum:
- channel_zone
example: channel_zone
type: string
updated_at:
description: ISO 8601 formatted date of when the channel zone was updated
example: '2019-01-23T18:10:02.574Z'
type: string
required:
- record_type
- countries
- id
- name
- channels
title: Channel zone object
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