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 Short Codes 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: Short codes
name: Short Codes
paths:
/short_codes:
get:
operationId: ListShortCodes
parameters:
- description: 'Consolidated filter parameter (deepObject style). Originally: filter[messaging_profile_id]'
explode: true
in: query
name: filter
schema:
properties:
messaging_profile_id:
description: Filter by Messaging Profile ID. Use the string `null` for phone numbers without assigned profiles. A synonym for the `/messaging_profiles/{id}/short_codes` endpoint when querying about an extant profile.
type: string
type: object
style: deepObject
- $ref: '#/components/parameters/PageConsolidated'
responses:
'200':
$ref: '#/components/responses/ListShortCodesResponse'
4XX:
$ref: '#/components/responses/messaging_GenericErrorResponse'
summary: List short codes
tags:
- Short Codes
x-group-parameters: 'true'
x-latency-category: responsive
/short_codes/{id}:
get:
operationId: RetrieveShortCode
parameters:
- $ref: '#/components/parameters/ShortCodeId'
responses:
'200':
$ref: '#/components/responses/ShortCodeResponse'
4XX:
$ref: '#/components/responses/messaging_GenericErrorResponse'
summary: Retrieve a short code
tags:
- Short Codes
x-latency-category: responsive
patch:
description: 'Update the settings for a specific short code. To unbind a short code from a profile, set the `messaging_profile_id` to `null` or an empty string.
To add or update tags, include the tags field as an array of strings.'
operationId: UpdateShortCode
parameters:
- $ref: '#/components/parameters/ShortCodeId'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateShortCodeRequest'
description: Short code update
required: true
responses:
'200':
$ref: '#/components/responses/ShortCodeResponse'
4XX:
$ref: '#/components/responses/messaging_GenericErrorResponse'
summary: Update short code
tags:
- Short Codes
x-latency-category: responsive
components:
schemas:
messaging_Errors:
properties:
errors:
items:
$ref: '#/components/schemas/messaging_Error'
type: array
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
UpdateShortCodeRequest:
example:
messaging_profile_id: abc85f64-5717-4562-b3fc-2c9600000000
tags:
- test_customer
properties:
messaging_profile_id:
description: Unique identifier for a messaging profile.
type: string
tags:
items:
type: string
type:
- array
required:
- messaging_profile_id
type: object
ShortCode:
example:
country_code: US
created_at: '2019-01-23T18:10:02.574Z'
id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
messaging_profile_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
record_type: short_code
short_code: '12345'
tags:
- test_customer
updated_at: '2019-01-23T18:10:02.574Z'
properties:
country_code:
description: ISO 3166-1 alpha-2 country code.
example: US
pattern: ^[A-Z]{2}$
readOnly: true
type: string
created_at:
description: ISO 8601 formatted date indicating when the resource was created.
format: date-time
readOnly: true
type: string
id:
description: Identifies the type of resource.
format: uuid
readOnly: true
type: string
messaging_profile_id:
description: Unique identifier for a messaging profile.
type:
- string
- 'null'
record_type:
description: Identifies the type of the resource.
enum:
- short_code
example: short_code
readOnly: true
type: string
short_code:
description: Short digit sequence used to address messages.
readOnly: true
type: string
tags:
items:
type: string
type:
- array
updated_at:
description: ISO 8601 formatted date indicating when the resource was updated.
format: date-time
readOnly: true
type: string
required:
- messaging_profile_id
type: object
responses:
messaging_GenericErrorResponse:
content:
application/json:
schema:
$ref: '#/components/schemas/messaging_Errors'
description: Unexpected error
ShortCodeResponse:
content:
application/json:
schema:
properties:
data:
$ref: '#/components/schemas/ShortCode'
title: Short Code Response
type: object
description: Successful response with details about a short code.
ListShortCodesResponse:
content:
application/json:
schema:
properties:
data:
items:
$ref: '#/components/schemas/ShortCode'
type: array
meta:
$ref: '#/components/schemas/messaging_PaginationMeta'
title: List Short Codes Response
type: object
description: Successful response with a list of short codes.
parameters:
ShortCodeId:
description: The id of the short code
in: path
name: id
required: true
schema:
format: uuid
type: string
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