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 Hosted 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: Manage your messaging hosted numbers
name: Hosted Numbers
paths:
/messaging_hosted_number_orders:
get:
operationId: ListMessagingHostedNumberOrders
parameters:
- $ref: '#/components/parameters/PageConsolidated'
responses:
'200':
$ref: '#/components/responses/ListMessagingHostedNumberOrdersResponse'
4XX:
$ref: '#/components/responses/messaging_GenericErrorResponse'
summary: List messaging hosted number orders
tags:
- Hosted Numbers
x-group-parameters: 'true'
x-latency-category: responsive
post:
operationId: CreateMessagingHostedNumberOrder
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateMessagingHostedNumberOrderRequest'
description: Message payload
responses:
'200':
$ref: '#/components/responses/MessagingHostedNumberOrderResponse'
4XX:
$ref: '#/components/responses/messaging_GenericErrorResponse'
summary: Create a messaging hosted number order
tags:
- Hosted Numbers
x-latency-category: responsive
/messaging_hosted_number_orders/eligibility_numbers_check:
post:
operationId: CheckEligibilityNumbers
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/EligibilityNumbersRequest'
description: Phone numbers to check eligibility
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/EligibilityNumbersResponse'
description: Successful response
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/messaging_Error'
description: Bad request
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/messaging_Error'
description: Unauthorized
summary: Check hosted messaging eligibility
tags:
- Hosted Numbers
x-latency-category: responsive
/messaging_hosted_number_orders/{id}:
delete:
description: Delete a messaging hosted number order and all associated phone numbers.
operationId: DeleteMessagingHostedNumberOrder
parameters:
- description: Identifies the messaging hosted number order to delete.
in: path
name: id
required: true
schema:
type: string
responses:
'200':
$ref: '#/components/responses/MessagingHostedNumberOrderResponse'
4XX:
$ref: '#/components/responses/messaging_GenericErrorResponse'
summary: Delete a messaging hosted number order
tags:
- Hosted Numbers
x-latency-category: responsive
get:
operationId: GetMessagingHostedNumberOrder
parameters:
- description: Identifies the type of resource.
in: path
name: id
required: true
schema:
type: string
responses:
'200':
$ref: '#/components/responses/MessagingHostedNumberOrderResponse'
4XX:
$ref: '#/components/responses/messaging_GenericErrorResponse'
summary: Retrieve a messaging hosted number order
tags:
- Hosted Numbers
x-latency-category: responsive
/messaging_hosted_number_orders/{id}/actions/file_upload:
post:
operationId: UploadMessagingHostedNumberOrderFile
parameters:
- description: Identifies the type of resource.
in: path
name: id
required: true
schema:
type: string
requestBody:
content:
multipart/form-data:
encoding:
bill:
contentType: application/pdf
loa:
contentType: application/pdf
schema:
$ref: '#/components/schemas/UploadFileMessagingHostedNumberOrderRequest'
description: Message payload
responses:
'200':
$ref: '#/components/responses/MessagingHostedNumberOrderResponse'
4XX:
$ref: '#/components/responses/messaging_GenericErrorResponse'
summary: Upload hosted number document
tags:
- Hosted Numbers
x-latency-category: responsive
/messaging_hosted_number_orders/{id}/validation_codes:
post:
description: Validate the verification codes sent to the numbers of the hosted order. The verification codes must be created in the verification codes endpoint.
operationId: ValidateVerificationCodesForMessagingHostedNumberOrder
parameters:
- description: Order ID related to the validation codes.
in: path
name: id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationCodesRequest'
description: Message payload
responses:
'200':
$ref: '#/components/responses/ValidationCodesResponse'
4XX:
$ref: '#/components/responses/messaging_GenericErrorResponse'
summary: Validate hosted number codes
tags:
- Hosted Numbers
x-latency-category: responsive
/messaging_hosted_number_orders/{id}/verification_codes:
post:
description: Create verification codes to validate numbers of the hosted order. The verification codes will be sent to the numbers of the hosted order.
operationId: CreateVerificationCodesForMessagingHostedNumberOrder
parameters:
- description: Order ID to have a verification code created.
in: path
name: id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/VerificationCodesRequest'
description: Message payload
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/CreatedVerificationCodesResponse'
description: Verification codes created and sent to the phone numbers of the hosted order.
4XX:
$ref: '#/components/responses/messaging_GenericErrorResponse'
summary: Create hosted number verification codes
tags:
- Hosted Numbers
x-latency-category: responsive
/messaging_hosted_numbers/{id}:
delete:
operationId: DeleteMessagingHostedNumber
parameters:
- description: Identifies the type of resource.
in: path
name: id
required: true
schema:
type: string
responses:
'200':
$ref: '#/components/responses/MessagingHostedNumberOrderResponse'
4XX:
$ref: '#/components/responses/messaging_GenericErrorResponse'
summary: Delete a messaging hosted number
tags:
- Hosted Numbers
x-latency-category: responsive
components:
responses:
messaging_GenericErrorResponse:
content:
application/json:
schema:
$ref: '#/components/schemas/messaging_Errors'
description: Unexpected error
ListMessagingHostedNumberOrdersResponse:
content:
application/json:
schema:
properties:
data:
items:
$ref: '#/components/schemas/MessagingHostedNumberOrder'
type: array
meta:
$ref: '#/components/schemas/messaging_PaginationMeta'
title: List Messaging Hosted Number Order Response
type: object
description: Successful response with a list of messaging hosted number orders.
ValidationCodesResponse:
content:
application/json:
schema:
properties:
data:
$ref: '#/components/schemas/ValidationCodes'
title: Retrieve Messaging Hosted Number Response
type: object
description: Successful response with the phone numbers and their respective status of the validation codes.
MessagingHostedNumberOrderResponse:
content:
application/json:
schema:
properties:
data:
$ref: '#/components/schemas/MessagingHostedNumberOrder'
title: Retrieve Messaging Hosted Number Order Response
type: object
description: Successful response with details about a messaging hosted number order.
schemas:
CreateMessagingHostedNumberOrderRequest:
example:
messaging_profile_id: dc8f39ac-953d-4520-b93b-786ae87db0da
phone_numbers:
- '+18665550001'
- '+18665550002'
properties:
messaging_profile_id:
description: Automatically associate the number with this messaging profile ID when the order is complete.
type: string
phone_numbers:
description: Phone numbers to be used for hosted messaging.
items:
type: string
x-format: +E.164
type: array
type: object
MessagingHostedNumberOrder:
example:
id: 86f58db9-0fe3-4adc-9d1f-46e66e6e9323
messaging_profile_id: dc8f39ac-953d-4520-b93b-786ae87db0da
phone_numbers:
- id: bf6307bd-884d-4c1f-b6ea-c62b8c495d3c
phone_number: '+18665550001'
record_type: messaging_hosted_number
status: pending
- id: 464bd54e-a328-4b11-a131-28e6793cb6f2
phone_number: '+18665550002'
record_type: messaging_hosted_number
status: pending
record_type: messaging_hosted_number_order
status: pending
properties:
id:
description: Resource unique identifier.
format: uuid
readOnly: true
type: string
messaging_profile_id:
description: Automatically associate the number with this messaging profile ID when the order is complete.
type:
- string
- 'null'
phone_numbers:
items:
$ref: '#/components/schemas/HostedNumber'
type: array
record_type:
description: Identifies the type of the resource.
example: messaging_hosted_number_order
readOnly: true
type: string
status:
enum:
- carrier_rejected
- compliance_review_failed
- deleted
- failed
- incomplete_documentation
- incorrect_billing_information
- ineligible_carrier
- loa_file_invalid
- loa_file_successful
- pending
- provisioning
- successful
type: string
type: object
HostedNumber:
example:
id: bf6307bd-884d-4c1f-b6ea-c62b8c495d3c
phone_number: '+18665550001'
record_type: messaging_hosted_number
status: successful
properties:
id:
description: Identifies the type of resource.
format: uuid
readOnly: true
type: string
phone_number:
description: The messaging hosted phone number (+E.164 format)
type: string
x-format: +E.164
record_type:
example: messaging_hosted_number
type: string
status:
enum:
- deleted
- failed
- failed_activation
- failed_carrier_rejected
- failed_ineligible_carrier
- failed_number_already_hosted
- failed_number_not_found
- failed_ownership_verification
- failed_timeout
- pending
- provisioning
- successful
type: string
type: object
EligibilityNumbersResponse:
properties:
phone_numbers:
description: List of phone numbers with their eligibility status.
items:
$ref: '#/components/schemas/EligibilityNumberResponse'
type: array
type: object
CreatedVerificationCodesResponse:
properties:
data:
items:
description: Verification code result response
properties:
error:
description: Error message describing why the verification code creation failed
type: string
phone_number:
description: Phone number for which the verification code was created
type: string
x-format: +E.164
type:
description: Type of verification method used
enum:
- sms
- call
type: string
verification_code_id:
description: Unique identifier for the verification code
format: uuid
type: string
required:
- phone_number
title: VerificationCodeResult
type: object
type: array
required:
- data
type: object
ValidationCodes:
properties:
order_id:
format: uuid
type: string
phone_numbers:
items:
properties:
phone_number:
type: string
x-format: +E.164
status:
enum:
- verified
- rejected
- already_verified
type: string
required:
- phone_number
- status
type: object
type: array
required:
- phone_numbers
- order_id
type: object
EligibilityNumberResponse:
properties:
detail:
description: Detailed information about the eligibility status.
type: string
eligible:
description: Whether the phone number is eligible for hosted messaging.
type: boolean
eligible_status:
description: The eligibility status of the phone number.
enum:
- NUMBER_CAN_NOT_BE_REPEATED
- NUMBER_CAN_NOT_BE_VALIDATED
- NUMBER_CAN_NOT_BE_WIRELESS
- NUMBER_CAN_NOT_BE_ACTIVE_IN_YOUR_ACCOUNT
- NUMBER_CAN_NOT_HOSTED_WITH_A_TELNYX_SUBSCRIBER
- NUMBER_CAN_NOT_BE_IN_TELNYX
- NUMBER_IS_NOT_A_US_NUMBER
- NUMBER_IS_NOT_A_VALID_ROUTING_NUMBER
- NUMBER_IS_NOT_IN_E164_FORMAT
- BILLING_ACCOUNT_CHECK_FAILED
- BILLING_ACCOUNT_IS_ABOLISHED
- ELIGIBLE
type: string
phone_number:
description: The phone number in e164 format.
type: string
type: object
VerificationCodesRequest:
properties:
phone_numbers:
items:
type: string
x-format: +E.164
type: array
verification_method:
enum:
- sms
- call
type: string
required:
- phone_numbers
- verification_method
type: object
UploadFileMessagingHostedNumberOrderRequest:
example:
bill: bill example
loa: example loa
properties:
bill:
description: Must be the last month's bill with proof of ownership of all of the numbers in the order in PDF format.
format: binary
type: string
loa:
description: Must be a signed LOA for the numbers in the order in PDF format.
format: binary
type: string
type: object
messaging_Errors:
properties:
errors:
items:
$ref: '#/components/schemas/messaging_Error'
type: array
EligibilityNumbersRequest:
properties:
phone_numbers:
description: List of phone numbers to check eligibility
items:
description: Phone number to check eligibility
type: string
x-format: +E.164
type: array
required:
- phone_numbers
type: object
ValidationCodesRequest:
properties:
verification_codes:
items:
properties:
code:
type: string
phone_number:
type: string
x-format: +E.164
required:
- phone_number
- code
type: object
type: array
required:
- verification_codes
type: object
messaging_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
required:
- total_pages
- total_results
- page_size
- page_number
type: object
messaging_Error:
properties:
code:
type: string
x-format: integer
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.
format: json-pointer
type: string
type: object
title:
type: string
required:
- code
- title
parameters:
PageConsolidated:
description: 'Consolidated page parameter (deepObject style). Originally: page[number], page[size]'
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
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