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 Phone Number Reservations 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: Number reservations
name: Phone Number Reservations
paths:
/number_reservations:
get:
description: Gets a paginated list of phone number reservations.
operationId: ListNumberReservations
parameters:
- $ref: '#/components/parameters/numbers_PageConsolidated'
- description: 'Consolidated filter parameter (deepObject style). Originally: filter[status], filter[created_at], filter[phone_numbers.phone_number], filter[customer_reference]'
explode: true
in: query
name: filter
schema:
properties:
created_at:
additionalProperties: false
description: Filter number reservations by date range.
properties:
gt:
description: Filter number reservations later than this value.
type: string
lt:
description: Filter number reservations earlier than this value.
type: string
type: object
customer_reference:
description: Filter number reservations via the customer reference set.
type: string
phone_numbers.phone_number:
description: Filter number reservations having these phone numbers.
type: string
status:
description: Filter number reservations by status.
type: string
type: object
style: deepObject
responses:
'200':
$ref: '#/components/responses/ListNumberReservationsResponse'
'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 number reservations
tags:
- Phone Number Reservations
x-group-parameters: 'true'
x-latency-category: responsive
post:
description: Creates a Phone Number Reservation for multiple numbers.
operationId: CreateNumberReservation
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateNumberReservationRequest'
required: true
responses:
'200':
$ref: '#/components/responses/NumberReservationResponse'
'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: Create a number reservation
tags:
- Phone Number Reservations
x-latency-category: responsive
/number_reservations/{number_reservation_id}:
get:
description: Gets a single phone number reservation.
operationId: RetrieveNumberReservation
parameters:
- description: The number reservation ID.
in: path
name: number_reservation_id
required: true
schema:
type: string
responses:
'200':
$ref: '#/components/responses/NumberReservationResponse'
'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 number reservation
tags:
- Phone Number Reservations
x-latency-category: responsive
/number_reservations/{number_reservation_id}/actions/extend:
post:
description: Extends reservation expiry time on all phone numbers.
operationId: ExtendNumberReservationExpiryTime
parameters:
- description: The number reservation ID.
in: path
name: number_reservation_id
required: true
schema:
type: string
responses:
'200':
$ref: '#/components/responses/NumberReservationResponse'
'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: Extend a number reservation
tags:
- Phone Number Reservations
x-latency-category: responsive
components:
schemas:
ReservedPhoneNumber:
example:
created_at: '2018-01-01T00:00:00.000000Z'
expired_at: '2018-01-01T00:00:00.000000Z'
id: 12ade33a-21c0-473b-b055-b3c836e1c292
phone_number: '+19705555098'
record_type: reserved_phone_number
status: pending
updated_at: '2018-01-01T00:00:00.000000Z'
properties:
created_at:
description: An ISO 8901 datetime string denoting when the individual number reservation was created.
example: '2018-01-01T00:00:00.000000Z'
format: date-time
readOnly: true
type: string
errors:
description: Errors the reservation could happen upon
example: Number is already on hold
readOnly: true
type: string
expired_at:
description: An ISO 8901 datetime string for when the individual number reservation is going to expire
example: '2018-01-01T00:00:00.000000Z'
format: date-time
readOnly: true
type: string
id:
example: 12ade33a-21c0-473b-b055-b3c836e1c292
format: uuid
readOnly: true
type: string
phone_number:
example: '+19705555098'
type: string
record_type:
example: reserved_phone_number
readOnly: true
type: string
status:
description: The status of the phone number's reservation.
enum:
- pending
- success
- failure
example: success
readOnly: true
type: string
updated_at:
description: An ISO 8901 datetime string for when the the individual number reservation was updated.
example: '2018-01-01T00:00:00.000000Z'
format: date-time
readOnly: true
type: string
type: object
NumberReservation:
example:
created_at: '2018-01-01T00:00:00.000000Z'
customer_reference: MY REF 001
id: 12ade33a-21c0-473b-b055-b3c836e1c292
phone_numbers:
- created_at: '2018-01-01T00:00:00.000000Z'
errors: Number is already on hold
expired_at: '2018-01-01T00:00:00.000000Z'
id: 12ade33a-21c0-473b-b055-b3c836e1c292
phone_number: '+19705555098'
record_type: reserved_phone_number
status: pending
updated_at: '2018-01-01T00:00:00.000000Z'
record_type: number_reservation
status: pending
updated_at: '2018-01-01T00:00:00.000000Z'
properties:
created_at:
description: An ISO 8901 datetime string denoting when the numbers reservation was created.
example: '2018-01-01T00:00:00.000000Z'
format: date-time
readOnly: true
type: string
customer_reference:
description: A customer reference string for customer look ups.
example: MY REF 001
type: string
errors:
description: Errors the reservation could happen upon
example: Number is already on hold
readOnly: true
type: string
id:
example: 12ade33a-21c0-473b-b055-b3c836e1c292
format: uuid
readOnly: true
type: string
phone_numbers:
items:
$ref: '#/components/schemas/ReservedPhoneNumber'
type: array
record_type:
example: number_reservation
readOnly: true
type: string
status:
description: The status of the entire reservation.
enum:
- pending
- success
- failure
readOnly: true
type: string
updated_at:
description: An ISO 8901 datetime string for when the number reservation was updated.
example: '2018-01-01T00:00:00.000000Z'
format: date-time
readOnly: true
type: string
type: object
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
CreateNumberReservationRequest:
example:
created_at: '2018-01-01T00:00:00.000000Z'
customer_reference: MY REF 001
id: 12ade33a-21c0-473b-b055-b3c836e1c292
phone_numbers:
- created_at: '2018-01-01T00:00:00.000000Z'
errors: Number is already on hold
expired_at: '2018-01-01T00:00:00.000000Z'
id: 12ade33a-21c0-473b-b055-b3c836e1c292
phone_number: '+19705555098'
record_type: reserved_phone_number
status: pending
updated_at: '2018-01-01T00:00:00.000000Z'
record_type: number_reservation
status: pending
updated_at: '2018-01-01T00:00:00.000000Z'
properties:
created_at:
description: An ISO 8901 datetime string denoting when the numbers reservation was created.
example: '2018-01-01T00:00:00.000000Z'
format: date-time
readOnly: true
type: string
customer_reference:
description: A customer reference string for customer look ups.
example: MY REF 001
type: string
id:
example: 12ade33a-21c0-473b-b055-b3c836e1c292
format: uuid
readOnly: true
type: string
phone_numbers:
items:
$ref: '#/components/schemas/ReservedPhoneNumber'
type: array
record_type:
example: number_reservation
readOnly: true
type: string
status:
description: The status of the entire reservation.
enum:
- pending
- success
- failure
readOnly: true
type: string
updated_at:
description: An ISO 8901 datetime string for when the number reservation was updated.
example: '2018-01-01T00:00:00.000000Z'
format: date-time
readOnly: true
type: string
type: object
numbers_Errors:
properties:
errors:
items:
$ref: '#/components/schemas/numbers_Error'
type: array
type: object
numbers_Error:
properties:
code:
example: '10007'
type: string
detail:
example: An unexpected error occured.
type: string
meta:
properties:
url:
description: URL with additional information on the error.
example: https://developers.telnyx.com/docs/overview/errors/10015
type: string
type: object
source:
properties:
parameter:
description: Indicates which query parameter caused the error.
type: string
pointer:
description: JSON pointer (RFC6901) to the offending entity.
example: /base
type: string
type: object
title:
example: Unexpected error
type: string
type: object
parameters:
numbers_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:
numbers_UnprocessableEntity:
content:
application/json:
schema:
$ref: '#/components/schemas/numbers_Errors'
description: Unprocessable entity. Check the 'detail' field in response for details.
numbers_NotFoundResponse:
content:
application/json:
schema:
$ref: '#/components/schemas/numbers_Errors'
description: The requested resource doesn't exist.
ListNumberReservationsResponse:
content:
application/json:
schema:
properties:
data:
items:
$ref: '#/components/schemas/NumberReservation'
type: array
meta:
$ref: '#/components/schemas/PaginationMeta'
title: List Number Reservations Response
type: object
description: Successful response with a list of number reservations.
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
numbers_GenericErrorResponse:
content:
application/json:
schema:
$ref: '#/components/schemas/numbers_Errors'
description: Unexpected error
NumberReservationResponse:
content:
application/json:
schema:
properties:
data:
$ref: '#/components/schemas/NumberReservation'
title: Number Reservation Response
type: object
description: Successful response with details about a number reservation.
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.
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