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 Requirement Groups 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: Requirement Groups
name: Requirement Groups
paths:
/number_order_phone_numbers/{id}/requirement_group:
post:
operationId: updateNumberOrderPhoneNumberRequirementGroup
parameters:
- description: The unique identifier of the number order phone number
in: path
name: id
required: true
schema:
format: uuid
type: string
requestBody:
content:
application/json:
schema:
properties:
requirement_group_id:
description: The ID of the requirement group to associate
format: uuid
type: string
required:
- requirement_group_id
type: object
required: true
responses:
'200':
content:
application/json:
schema:
properties:
data:
$ref: '#/components/schemas/NumberOrderPhoneNumberRequirementGroupResponse'
type: object
description: Successful response with updated phone number order details
'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 requirement group for a phone number order
tags:
- Requirement Groups
x-latency-category: responsive
/requirement_groups:
get:
operationId: GetRequirementGroups
parameters:
- description: 'Consolidated filter parameter (deepObject style). Originally: filter[country_code], filter[phone_number_type], filter[action], filter[status], filter[customer_reference]'
explode: true
in: query
name: filter
schema:
properties:
action:
description: Filter requirement groups by action type
enum:
- ordering
- porting
- action
type: string
country_code:
description: Filter requirement groups by country code (iso alpha 2)
type: string
customer_reference:
description: Filter requirement groups by customer reference
type: string
phone_number_type:
description: Filter requirement groups by phone number type.
enum:
- local
- toll_free
- mobile
- national
- shared_cost
type: string
status:
description: Filter requirement groups by status
enum:
- approved
- unapproved
- pending-approval
- declined
- expired
type: string
type: object
style: deepObject
responses:
'200':
content:
application/json:
schema:
items:
$ref: '#/components/schemas/RequirementGroup'
type: array
description: List requirement groups
'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: List requirement groups
tags:
- Requirement Groups
x-latency-category: responsive
post:
operationId: CreateRequirementGroup
requestBody:
content:
application/json:
schema:
properties:
action:
enum:
- ordering
- porting
example: ordering
type: string
country_code:
description: ISO alpha 2 country code
example: US
type: string
customer_reference:
example: My Requirement Group
type: string
phone_number_type:
enum:
- local
- toll_free
- mobile
- national
- shared_cost
example: local
type: string
regulatory_requirements:
items:
properties:
field_value:
type: string
requirement_id:
type: string
type: object
type: array
required:
- country_code
- phone_number_type
- action
type: object
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/RequirementGroup'
description: Requirement group created
'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 new requirement group
tags:
- Requirement Groups
x-latency-category: responsive
/requirement_groups/{id}:
delete:
operationId: DeleteRequirementGroup
parameters:
- description: ID of the requirement group
in: path
name: id
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/RequirementGroup'
description: Deleted requirement group
'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: Delete a requirement group by ID
tags:
- Requirement Groups
x-latency-category: responsive
get:
operationId: GetRequirementGroup
parameters:
- description: ID of the requirement group to retrieve
in: path
name: id
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/RequirementGroup'
description: A single requirement group
'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: Get a single requirement group by ID
tags:
- Requirement Groups
x-latency-category: responsive
patch:
operationId: UpdateRequirementGroup
parameters:
- description: ID of the requirement group
in: path
name: id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
properties:
customer_reference:
description: Reference for the customer
example: '0002'
type: string
regulatory_requirements:
items:
properties:
field_value:
description: New value for the regulatory requirement
example: new requirement value
type: string
requirement_id:
description: Unique identifier for the regulatory requirement
example: 53970723-fbff-4f46-a975-f62be6c1a585
type: string
type: object
type: array
type: object
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/RequirementGroup'
description: Updated requirement group
'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 requirement values in requirement group
tags:
- Requirement Groups
x-latency-category: responsive
/requirement_groups/{id}/submit_for_approval:
post:
operationId: SubmitRequirementGroup
parameters:
- description: ID of the requirement group to submit
in: path
name: id
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/RequirementGroup'
description: A single requirement group
'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: Submit a Requirement Group for Approval
tags:
- Requirement Groups
x-latency-category: responsive
/sub_number_orders/{id}/requirement_group:
post:
operationId: updateSubNumberOrderRequirementGroup
parameters:
- description: The ID of the sub number order
in: path
name: id
required: true
schema:
format: uuid
type: string
requestBody:
content:
application/json:
example:
requirement_group_id: a4b201f9-8646-4e54-a7d2-b2e403eeaf8c
schema:
properties:
requirement_group_id:
description: The ID of the requirement group to associate
format: uuid
type: string
required:
- requirement_group_id
type: object
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/SubNumberOrderRequirementGroupResponse'
description: Sub number order requirement group updated successfully
'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 requirement group for a sub number order
tags:
- Requirement Groups
x-latency-category: responsive
components:
schemas:
RequirementGroup:
properties:
action:
type: string
country_code:
type: string
created_at:
format: date-time
type: string
customer_reference:
type: string
id:
type: string
phone_number_type:
type: string
record_type:
example: requirement_group
type: string
regulatory_requirements:
items:
$ref: '#/components/schemas/UserRequirement'
type: array
status:
enum:
- approved
- unapproved
- pending-approval
- declined
- expired
type: string
updated_at:
format: date-time
type: string
type: object
UserRequirement:
properties:
created_at:
format: date-time
type: string
expires_at:
format: date-time
type: string
field_type:
type: string
field_value:
type: string
requirement_id:
type: string
status:
enum:
- approved
- unapproved
- pending-approval
- declined
- expired
type: string
updated_at:
format: date-time
type: string
type: object
NumberOrderPhoneNumberRequirementGroupResponse:
properties:
bundle_id:
format: uuid
type:
- string
- 'null'
country_code:
example: AT
type: string
deadline:
format: date-time
type: string
id:
example: 613d517a-0432-4bae-a785-c11033bd0985
format: uuid
type: string
is_block_number:
example: false
type: boolean
locality:
example: AUSTRIA
type: string
order_request_id:
example: a11d58fe-88a4-494a-b752-8dea411993c6
format: uuid
type: string
phone_number:
example: '+43800300238'
type: string
phone_number_type:
example: toll_free
type: string
record_type:
example: number_order_phone_number
type: string
regulatory_requirements:
items:
properties:
field_type:
example: textual
type: string
field_value:
example: '1234567890'
type: string
requirement_id:
format: uuid
type: string
status:
example: pending-approval
type: string
type: object
type: array
requirements_met:
example: false
type: boolean
requirements_status:
example: requirement-info-under-review
type: string
status:
example: pending
type: string
sub_number_order_id:
example: f826ed66-b27c-4340-9dc0-57dc3459f1bd
format: uuid
type: string
type: object
SubNumberOrderRequirementGroupResponse:
example:
data:
country_code: AT
created_at: '2018-01-01T00:00:00.000000Z'
customer_reference: missing
id: f826ed66-b27c-4340-9dc0-57dc3459f1bd
is_block_sub_number_order: false
order_request_id: a11d58fe-88a4-494a-b752-8dea411993c6
phone_number_type: toll_free
phone_numbers:
- bundle_id: a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d
country_code: AT
id: 613d517a-0432-4bae-a785-c11033bd0985
phone_number: '+43800300238'
phone_number_type: toll_free
record_type: number_order_phone_number
regulatory_requirements:
- field_type: textual
field_value: '4804570924'
requirement_id: 2708e569-696a-4fc7-9305-5fdb3eb9c7dd
status: pending-approval
requirements_met: false
requirements_status: requirement-info-under-review
status: pending
phone_numbers_count: 1
record_type: sub_number_order
regulatory_requirements:
- field_type: textual
record_type: phone_number_regulatory_requirement
requirement_id: 2708e569-696a-4fc7-9305-5fdb3eb9c7dd
requirements_met: false
status: pending
updated_at: '2018-01-01T00:00:00.000000Z'
properties:
data:
properties:
country_code:
type: string
created_at:
format: date-time
type: string
customer_reference:
type: string
id:
format: uuid
type: string
is_block_sub_number_order:
type: boolean
order_request_id:
format: uuid
type: string
phone_number_type:
type: string
phone_numbers:
items:
$ref: '#/components/schemas/SubNumberOrderPhoneNumber'
type: array
phone_numbers_count:
type: integer
record_type:
type: string
regulatory_requirements:
items:
$ref: '#/components/schemas/RegulatoryRequirement'
type: array
requirements_met:
type: boolean
status:
type: string
updated_at:
format: date-time
type: string
type: object
type: object
RegulatoryRequirement:
properties:
field_type:
type: string
record_type:
type: string
requirement_id:
format: uuid
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
SubNumberOrderPhoneNumber:
properties:
bundle_id:
format: uuid
type:
- string
- 'null'
country_code:
type: string
id:
format: uuid
type: string
phone_number:
type: string
phone_number_type:
type: string
record_type:
type: string
regulatory_requirements:
items:
properties:
field_type:
type: string
field_value:
type: string
requirement_id:
format: uuid
type: string
status:
type: string
type: object
type: array
requirements_met:
type: boolean
requirements_status:
type: string
status:
type: string
type: object
responses:
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_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_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