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 Orders 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 orders
name: Phone Number Orders
paths:
/comments:
get:
operationId: ListComments
parameters:
- description: 'Consolidated filter parameter (deepObject style). Originally: filter[comment_record_type], filter[comment_record_id]'
explode: true
in: query
name: filter
schema:
properties:
comment_record_id:
description: ID of the record the comments relate to
example: 8ffb3622-7c6b-4ccc-b65f-7a3dc0099576
type: string
comment_record_type:
description: Record type that the comment relates to
enum:
- sub_number_order
- requirement_group
example: sub_number_order
type: string
type: object
style: deepObject
responses:
'200':
$ref: '#/components/responses/listCommentsResponse'
'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 all comments
tags:
- Phone Number Orders
x-latency-category: responsive
post:
operationId: CreateComment
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Comment'
required: true
responses:
'200':
$ref: '#/components/responses/CommentResponse'
'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 comment
tags:
- Phone Number Orders
x-latency-category: responsive
/comments/{id}:
get:
operationId: RetrieveComment
parameters:
- description: The comment ID.
in: path
name: id
required: true
schema:
type: string
responses:
'200':
$ref: '#/components/responses/CommentResponse'
'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 comment
tags:
- Phone Number Orders
x-latency-category: responsive
/comments/{id}/read:
patch:
operationId: MarkCommentRead
parameters:
- description: The comment ID.
in: path
name: id
required: true
schema:
type: string
responses:
'200':
$ref: '#/components/responses/ReadCommentResponse'
'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: Mark a comment as read
tags:
- Phone Number Orders
x-latency-category: responsive
/number_order_phone_numbers:
get:
description: Get a list of phone numbers associated to orders.
operationId: RetrieveOrderPhoneNumbers
parameters:
- description: 'Consolidated filter parameter (deepObject style). Originally: filter[country_code]'
explode: true
in: query
name: filter
schema:
properties:
country_code:
description: Country code of the order phone number.
example: US
type: string
type: object
style: deepObject
responses:
'200':
$ref: '#/components/responses/ListNumberOrderPhoneNumbersResponse'
'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 list of phone numbers associated to orders
tags:
- Phone Number Orders
x-latency-category: responsive
/number_order_phone_numbers/{number_order_phone_number_id}:
get:
description: Get an existing phone number in number order.
operationId: GetNumberOrderPhoneNumber
parameters:
- description: The number order phone number ID.
in: path
name: number_order_phone_number_id
required: true
schema:
type: string
responses:
'200':
$ref: '#/components/responses/NumberOrderPhoneNumberResponse'
'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 single phone number within a number order.
tags:
- Phone Number Orders
x-latency-category: responsive
patch:
description: Updates requirements for a single phone number within a number order.
operationId: UpdateNumberOrderPhoneNumber
parameters:
- description: The number order phone number ID.
in: path
name: number_order_phone_number_id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateNumberOrderPhoneNumberRequest'
required: true
responses:
'200':
$ref: '#/components/responses/NumberOrderPhoneNumberResponse'
'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 requirements for a single phone number within a number order.
tags:
- Phone Number Orders
x-latency-category: responsive
/number_orders:
get:
description: Get a paginated list of number orders.
operationId: ListNumberOrders
parameters:
- $ref: '#/components/parameters/numbers_PageConsolidated'
- description: 'Consolidated filter parameter (deepObject style). Originally: filter[status], filter[created_at], filter[phone_numbers_count], filter[customer_reference], filter[requirements_met]'
explode: true
in: query
name: filter
schema:
properties:
created_at:
additionalProperties: false
description: Filter number orders by date range.
properties:
gt:
description: Filter number orders later than this value.
type: string
lt:
description: Filter number orders earlier than this value.
type: string
type: object
customer_reference:
description: Filter number orders via the customer reference set.
type: string
phone_numbers_count:
description: Filter number order with this amount of numbers
type: string
requirements_met:
description: Filter number orders by requirements met.
type: boolean
status:
description: Filter number orders by status.
type: string
type: object
style: deepObject
responses:
'200':
$ref: '#/components/responses/ListNumberOrdersResponse'
'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 orders
tags:
- Phone Number Orders
x-endpoint-cost: medium
x-group-parameters: 'true'
x-latency-category: responsive
post:
description: Creates a phone number order.
operationId: CreateNumberOrder
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateNumberOrderRequest'
required: true
responses:
'200':
$ref: '#/components/responses/NumberOrderResponse'
'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 order
tags:
- Phone Number Orders
x-endpoint-cost: heavy
x-latency-category: responsive
/number_orders/{number_order_id}:
get:
description: Get an existing phone number order.
operationId: RetrieveNumberOrder
parameters:
- description: The number order ID.
in: path
name: number_order_id
required: true
schema:
type: string
responses:
'200':
$ref: '#/components/responses/NumberOrderResponse'
'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 order
tags:
- Phone Number Orders
x-latency-category: responsive
patch:
description: Updates a phone number order.
operationId: UpdateNumberOrder
parameters:
- description: The number order ID.
in: path
name: number_order_id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateNumberOrderRequest'
required: true
responses:
'200':
$ref: '#/components/responses/NumberOrderResponse'
'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 number order
tags:
- Phone Number Orders
x-latency-category: responsive
/sub_number_orders:
get:
description: Get a paginated list of sub number orders.
operationId: ListSubNumberOrders
parameters:
- description: 'Consolidated filter parameter (deepObject style). Originally: filter[status], filter[order_request_id], filter[country_code], filter[phone_number_type], filter[phone_numbers_count]'
explode: true
in: query
name: filter
schema:
properties:
country_code:
description: ISO alpha-2 country code.
example: US
type: string
order_request_id:
description: ID of the number order the sub number order belongs to
example: 12ade33a-21c0-473b-b055-b3c836e1c293
format: uuid
type: string
phone_number_type:
description: Phone Number Type
example: local
type: string
phone_numbers_count:
description: Amount of numbers in the sub number order
example: 1
type: integer
status:
description: Filter sub number orders by status.
type: string
type: object
style: deepObject
responses:
'200':
$ref: '#/components/responses/ListSubNumberOrdersResponse'
'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 sub number orders
tags:
- Phone Number Orders
x-group-parameters: 'true'
x-latency-category: responsive
/sub_number_orders/{sub_number_order_id}:
get:
description: Get an existing sub number order.
operationId: GetSubNumberOrder
parameters:
- description: The sub number order ID.
in: path
name: sub_number_order_id
required: true
schema:
type: string
- description: 'Consolidated filter parameter (deepObject style). Originally: filter[include_phone_numbers]'
explode: true
in: query
name: filter
schema:
properties:
include_phone_numbers:
default: false
description: Include the first 50 phone number objects in the results
type: boolean
type: object
style: deepObject
responses:
'200':
$ref: '#/components/responses/SubNumberOrderResponse'
'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 sub number order
tags:
- Phone Number Orders
x-latency-category: responsive
patch:
description: Updates a sub number order.
operationId: UpdateSubNumberOrder
parameters:
- description: The sub number order ID.
in: path
name: sub_number_order_id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateSubNumberOrderRequest'
required: true
responses:
'200':
$ref: '#/components/responses/SubNumberOrderResponse'
'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 sub number order's requirements
tags:
- Phone Number Orders
x-latency-category: responsive
/sub_number_orders/{sub_number_order_id}/cancel:
patch:
description: Allows you to cancel a sub number order in 'pending' status.
operationId: CancelSubNumberOrder
parameters:
- description: The ID of the sub number order.
in: path
name: sub_number_order_id
required: true
schema:
type: string
responses:
'200':
$ref: '#/components/responses/SubNumberOrderResponse'
'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: Cancel a sub number order
tags:
- Phone Number Orders
x-latency-category: responsive
/sub_number_orders_report:
post:
description: Create a CSV report for sub number orders. The report will be generated asynchronously and can be downloaded once complete.
operationId: CreateSubNumberOrdersReport
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateSubNumberOrdersReportRequest'
required: false
responses:
'202':
$ref: '#/components/responses/SubNumberOrdersReportResponse'
'400':
$ref: '#/components/responses/numbers_BadRequestResponse'
'401':
$ref: '#/components/responses/numbers_UnauthorizedResponse'
'422':
$ref: '#/components/responses/numbers_UnprocessableEntity'
'500':
$ref: '#/components/responses/numbers_GenericErrorResponse'
summary: Create a sub number orders report
tags:
- Phone Number Orders
x-endpoint-cost: medium
x-latency-category: background
/sub_number_orders_report/{report_id}:
get:
description: Get the status and details of a sub number orders report.
operationId: GetSubNumberOrdersReport
parameters:
- description: The unique identifier of the sub number orders report
example: 12ade33a-21c0-473b-b055-b3c836e1c293
in: path
name: report_id
required: true
schema:
format: uuid
type: string
responses:
'200':
$ref: '#/components/responses/SubNumberOrdersReportResponse'
'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 sub number orders report
tags:
- Phone Number Orders
x-endpoint-cost: light
x-latency-category: responsive
/sub_number_orders_report/{report_id}/download:
get:
description: Download the CSV file for a completed sub number orders report. The report status must be 'success' before the file can be downloaded.
operationId: DownloadSubNumberOrdersReport
parameters:
- description: The unique identifier of the sub number orders report
example: 12ade33a-21c0-473b-b055-b3c836e1c293
in: path
name: report_id
required: true
schema:
format: uuid
type: string
responses:
'200':
content:
text/csv:
example: 'id,order_request_id,is_block_sub_number_order,status,phone_number_type,requirements_met,phone_numbers_count,country_code,user_id,customer_reference,created_at,updated_at
1758d6ed-61a0-4d7a-bf57-b5dced413d33,f486fc2c-4fdf-4849-930d-b3045373e839,False,success,local,True,1,US,0d7ef697-df19-413a-b724-56b0539f5397,STRING,2025-05-23 14:33:12.376686,2025-05-23 14:33:15.624916'
schema:
format: binary
type: string
description: CSV file download
'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: Download a sub number orders report
tags:
- Phone Number Orders
x-endpoint-cost: light
x-latency-category: background
components:
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.
SubNumberOrdersReportResponse:
content:
application/json:
schema:
properties:
data:
$ref: '#/components/schemas/SubNumberOrdersReport'
type: object
description: Sub number orders report response
ListNumberOrdersResponse:
content:
application/json:
schema:
properties:
data:
items:
$ref: '#/components/schemas/NumberOrder'
type: array
meta:
$ref: '#/components/schemas/PaginationMeta'
title: List Number Orders Response
type: object
description: Successful response with a list of number orders.
SubNumberOrderResponse:
content:
application/json:
schema:
properties:
data:
$ref: '#/components/schemas/SubNumberOrder'
title: Sub Number Order Response
type: object
description: Successful response with details about a sub number order.
ListNumberOrderPhoneNumbersResponse:
content:
application/json:
schema:
properties:
data:
items:
$ref: '#/components/schemas/NumberOrderPhoneNumber'
type: array
meta:
$ref: '#/components/schemas/PaginationMeta'
title: List Number Order Phone Numbers Response
type: object
description: Successful response with a list of number order phone numbers.
CommentResponse:
content:
application/json:
schema:
properties:
data:
allOf:
- $ref: '#/components/schemas/Comment'
- type: object
type: object
description: A Comment Response
ReadCommentResponse:
content:
application/json:
schema:
properties:
data:
allOf:
- $ref: '#/components/schemas/ReadComment'
- type: object
type: object
description: A Comment Response
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_NotFoundResponse:
content:
application/json:
schema:
$ref: '#/components/schemas/numbers_Errors'
description: The requested resource doesn't exist.
ListSubNumberOrdersResponse:
content:
application/json:
schema:
properties:
data:
items:
$ref: '#/components/schemas/SubNumberOrder'
type: array
meta:
$ref: '#/components/schemas/PaginationMeta'
title: List Sub Number Orders Response
type: object
description: Successful response with a list of sub number orders.
NumberOrderPhoneNumberResponse:
content:
application/json:
schema:
properties:
data:
$ref: '#/components/schemas/NumberOrderPhoneNumber'
title: Number Order Phone Number Response
type: object
description: Successful response with details about a number order phone number.
listCommentsResponse:
content:
application/json:
schema:
properties:
data:
items:
$ref: '#/components/schemas/Comment'
type: array
meta:
$ref: '#/components/schemas/PaginationMeta'
type: object
description: An array of Comment Responses
numbers_GenericErrorResponse:
content:
application/json:
schema:
$ref: '#/components/schemas/numbers_Errors'
description: Unexpected error
NumberOrderResponse:
content:
application/json:
schema:
properties:
data:
$ref: '#/components/schemas/NumberOrderWithPhoneNumbers'
title: Number Order Response
type: object
description: Successful response with details about a number order.
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.
schemas:
SubNumberOrderRegulatoryRequirement:
properties:
field_type:
enum:
- textual
- datetime
- address
- document
example: address
readOnly: true
type: string
record_type:
example: phone_number_regulatory_requirement
readOnly: true
type: string
requirement_id:
description: Unique id for a requirement.
example: 8ffb3622-7c6b-4ccc-b65f-7a3dc0099576
format: uuid
type: string
type: object
Comment:
properties:
body:
example: Hi there, ....
type: string
comment_record_id:
example: 8ffb3622-7c6b-4ccc-b65f-7a3dc0099576
format: uuid
type: string
comment_record_type:
enum:
- sub_number_order
- requirement_group
example: sub_number_order
type: string
commenter:
example: user@company.com
readOnly: true
type: string
commenter_type:
enum:
- admin
- user
example: user
readOnly: true
type: string
created_at:
description: An ISO 8901 datetime string denoting when the comment was created.
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
read_at:
description: An ISO 8901 datetime string for when the comment was read.
example: '2018-01-01T00:00:00.000000Z'
format: date-time
readOnly: true
type: string
updated_at:
description: An ISO 8901 datetime string for when the comment was updated.
example: '2018-01-01T00:00:00.000000Z'
format: date-time
readOnly: true
type: string
type: object
NumberOrderPhoneNumber:
properties:
bundle_id:
example: a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d
format: uuid
readOnly: true
type:
- string
- 'null'
country_code:
example: US
type: string
deadline:
example: '2024-05-31T11:14:00Z'
format: date-time
type: string
id:
example: dc8e4d67-33a0-4cbb-af74-7b58f05bd494
format: uuid
readOnly: true
type: string
is_block_number:
example: false
type: boolean
locality:
example: San Francisco
type: string
order_request_id:
example: dc8e4d67-33a0-4cbb-af74-7b58f05bd495
format: uuid
type: string
phone_number:
example: '+19705555098'
type: string
phone_number_type:
enum:
- local
- toll_free
- mobile
- national
- shared_cost
- landline
example: local
type: string
record_type:
example: number_order_phone_number
readOnly: true
type: string
regulatory_requirements:
items:
$ref: '#/components/schemas/SubNumberOrderRegulatoryRequirementWithValue'
type: array
requirements_met:
description: True if all requirements are met for a phone number, false otherwise.
example: true
readOnly: true
type: boolean
requirements_status:
description: Status of requirements (if applicable)
enum:
- pending
- approved
- cancelled
- deleted
- requirement-info-exception
- requirement-info-pending
- requirement-info-under-review
readOnly: true
type: string
status:
description: The status of the phone number in the order.
enum:
- pending
- success
- failure
readOnly: true
type: string
sub_number_order_id:
example: dc8e4d67-33a0-4cbb-af74-7b58f05bd496
format: uuid
type
# --- truncated at 32 KB (52 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/telnyx/refs/heads/main/openapi/telnyx-phone-number-orders-api-openapi.yml