Telnyx Phone Number Block Orders API
The Phone Number Block Orders API from Telnyx — 2 operation(s) for phone number block orders.
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 Block 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:
- name: Phone Number Block Orders
paths:
/number_block_orders:
get:
description: Get a paginated list of number block orders.
operationId: ListNumberBlockOrders
parameters:
- $ref: '#/components/parameters/numbers_PageConsolidated'
- description: 'Consolidated filter parameter (deepObject style). Originally: filter[status], filter[created_at], filter[phone_numbers.starting_number]'
explode: true
in: query
name: filter
schema:
properties:
created_at:
additionalProperties: false
description: Filter number block orders by date range.
properties:
gt:
description: Filter number block orders later than this value.
example: '2018-01-01T00:00:00.000000Z'
type: string
lt:
description: Filter number block orders earlier than this value.
example: '2018-01-01T00:00:00.000000Z'
type: string
type: object
phone_numbers.starting_number:
description: Filter number block orders having these phone numbers.
example: '+19705555000'
type: string
status:
description: Filter number block orders by status.
example: pending
type: string
type: object
style: deepObject
responses:
'200':
$ref: '#/components/responses/ListNumberBlockOrdersResponse'
'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 block orders
tags:
- Phone Number Block Orders
x-latency-category: responsive
post:
description: Creates a phone number block order.
operationId: CreateNumberBlockOrder
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateNumberBlockOrderRequest'
required: true
responses:
'200':
$ref: '#/components/responses/NumberBlockOrderResponse'
'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 block order
tags:
- Phone Number Block Orders
x-latency-category: responsive
/number_block_orders/{number_block_order_id}:
get:
description: Get an existing phone number block order.
operationId: RetrieveNumberBlockOrder
parameters:
- description: The number block order ID.
in: path
name: number_block_order_id
required: true
schema:
type: string
responses:
'200':
$ref: '#/components/responses/NumberBlockOrderResponse'
'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 block order
tags:
- Phone Number Block Orders
x-latency-category: responsive
components:
schemas:
CreateNumberBlockOrderRequest:
example:
range: 10
starting_number: '+19705555000'
properties:
connection_id:
description: Identifies the connection associated with this phone number.
example: '346789098765567'
type: string
created_at:
description: An ISO 8901 datetime string denoting when the number order 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
messaging_profile_id:
description: Identifies the messaging profile associated with the phone number.
example: abc85f64-5717-4562-b3fc-2c9600
type: string
phone_numbers_count:
description: The count of phone numbers in the number order.
example: 10
readOnly: true
type: integer
range:
description: The phone number range included in the block.
example: 10
type: integer
writeOnly: true
record_type:
example: number_block_order
readOnly: true
type: string
requirements_met:
description: True if all requirements are met for every phone number, false otherwise.
example: true
readOnly: true
type: boolean
starting_number:
description: Starting phone number block
example: '+19705555000'
type: string
writeOnly: true
status:
description: The status of the order.
enum:
- pending
- success
- failure
readOnly: true
type: string
updated_at:
description: An ISO 8901 datetime string for when the number order was updated.
example: '2018-01-01T00:00:00.000000Z'
format: date-time
readOnly: true
type: string
required:
- starting_number
- range
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
NumberBlockOrder:
example:
connection_id: '346789098765567'
created_at: '2018-01-01T00:00:00.000000Z'
customer_reference: MY REF 001
id: 12ade33a-21c0-473b-b055-b3c836e1c292
messaging_profile_id: abc85f64-5717-4562-b3fc-2c9600
phone_numbers_count: 10
range: 10
record_type: number_block_order
requirements_met: true
starting_number: '+19705555000'
status: pending
updated_at: '2018-01-01T00:00:00.000000Z'
properties:
connection_id:
description: Identifies the connection associated to all numbers in the phone number block.
example: '346789098765567'
type: string
created_at:
description: An ISO 8901 datetime string denoting when the number order 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
messaging_profile_id:
description: Identifies the messaging profile associated to all numbers in the phone number block.
example: abc85f64-5717-4562-b3fc-2c9600
type: string
phone_numbers_count:
description: The count of phone numbers in the number order.
example: 1
readOnly: true
type: integer
range:
description: The phone number range included in the block.
example: 10
type: integer
record_type:
example: number_block_order
readOnly: true
type: string
requirements_met:
description: True if all requirements are met for every phone number, false otherwise.
example: true
readOnly: true
type: boolean
starting_number:
description: Starting phone number block
example: '+19705555000'
type: string
status:
description: The status of the order.
enum:
- pending
- success
- failure
example: success
readOnly: true
type: string
updated_at:
description: An ISO 8901 datetime string for when the number order 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.
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
NumberBlockOrderResponse:
content:
application/json:
schema:
properties:
data:
$ref: '#/components/schemas/NumberBlockOrder'
title: Number Block Order Response
type: object
description: Successful response with details about a number block order.
ListNumberBlockOrdersResponse:
content:
application/json:
schema:
properties:
data:
items:
$ref: '#/components/schemas/NumberBlockOrder'
type: array
meta:
$ref: '#/components/schemas/PaginationMeta'
title: List Number Block Orders Response
type: object
description: Successful response with a list of number block orders.
numbers_GenericErrorResponse:
content:
application/json:
schema:
$ref: '#/components/schemas/numbers_Errors'
description: Unexpected error
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