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 Documents 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: Documents
name: Documents
paths:
/document_links:
get:
description: List all documents links ordered by created_at descending.
operationId: ListDocumentLinks
parameters:
- $ref: '#/components/parameters/FilterDocumentLinksConsolidated'
- $ref: '#/components/parameters/documents_PageConsolidated'
responses:
'200':
$ref: '#/components/responses/ListDocServiceDocumentLinksResponse'
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/documents_Errors'
description: Unprocessable entity. Check the 'detail' field in response for details.
default:
$ref: '#/components/responses/documents_GenericErrorResponse'
summary: List all document links
tags:
- Documents
x-latency-category: responsive
/documents:
get:
description: List all documents ordered by created_at descending.
operationId: ListDocuments
parameters:
- $ref: '#/components/parameters/FilterDocumentsConsolidated'
- $ref: '#/components/parameters/SortDocumentsConsolidated'
- $ref: '#/components/parameters/documents_PageConsolidated'
responses:
'200':
$ref: '#/components/responses/ListDocServiceDocumentsResponse'
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/documents_Errors'
description: Unprocessable entity. Check the 'detail' field in response for details.
default:
$ref: '#/components/responses/documents_GenericErrorResponse'
summary: List all documents
tags:
- Documents
x-latency-category: responsive
post:
description: Upload a document.<br /><br />Uploaded files must be linked to a service within 30 minutes or they will be automatically deleted.
operationId: CreateDocument
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateDocServiceDocumentRequest'
multipart/form-data:
schema:
$ref: '#/components/schemas/CreateMultiPartDocServiceDocumentRequest'
required: true
responses:
'200':
$ref: '#/components/responses/DocServiceDocumentResponse'
'422':
$ref: '#/components/responses/documents_UnprocessableEntity'
default:
$ref: '#/components/responses/documents_GenericErrorResponse'
summary: Upload a document
tags:
- Documents
x-latency-category: responsive
/documents/{id}:
delete:
description: Delete a document.<br /><br />A document can only be deleted if it's not linked to a service. If it is linked to a service, it must be unlinked prior to deleting.
operationId: DeleteDocument
parameters:
- $ref: '#/components/parameters/Id'
responses:
'200':
$ref: '#/components/responses/DocServiceDocumentResponse'
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/documents_Errors'
description: Unprocessable entity. Check the 'detail' field in response for details.
default:
$ref: '#/components/responses/documents_GenericErrorResponse'
summary: Delete a document
tags:
- Documents
x-latency-category: responsive
get:
description: Retrieve a document.
operationId: RetrieveDocument
parameters:
- $ref: '#/components/parameters/Id'
responses:
'200':
$ref: '#/components/responses/DocServiceDocumentResponse'
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/documents_Errors'
description: Unprocessable entity. Check the 'detail' field in response for details.
default:
$ref: '#/components/responses/documents_GenericErrorResponse'
summary: Retrieve a document
tags:
- Documents
x-latency-category: responsive
patch:
description: Update a document.
operationId: UpdateDocument
parameters:
- $ref: '#/components/parameters/Id'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/DocServiceDocument'
required: true
responses:
'200':
$ref: '#/components/responses/DocServiceDocumentResponse'
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/documents_Errors'
description: Unprocessable entity. Check the 'detail' field in response for details.
default:
$ref: '#/components/responses/documents_GenericErrorResponse'
summary: Update a document
tags:
- Documents
x-latency-category: responsive
/documents/{id}/download:
get:
description: Download a document.
operationId: DownloadDocument
parameters:
- $ref: '#/components/parameters/Id'
responses:
'200':
$ref: '#/components/responses/DownloadDocServiceDocumentResponse'
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/documents_Errors'
description: Unprocessable entity. Check the 'detail' field in response for details.
default:
$ref: '#/components/responses/documents_GenericErrorResponse'
summary: Download a document
tags:
- Documents
x-latency-category: responsive
/documents/{id}/download_link:
get:
description: Generates a temporary pre-signed URL that can be used to download the document directly from the storage backend without authentication.
operationId: getDocumentDownloadLink
parameters:
- description: Uniquely identifies the document
in: path
name: id
required: true
schema:
example: 550e8400-e29b-41d4-a716-446655440000
format: uuid
type: string
responses:
'200':
content:
application/json:
schema:
properties:
data:
properties:
url:
description: Pre-signed temporary URL for downloading the document
example: https://s3.amazonaws.com/bucket/path/to/document?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=...
format: uri
type: string
required:
- url
type: object
required:
- data
type: object
description: Successfully generated download link
'404':
$ref: '#/components/responses/ResourceNotFound'
'422':
$ref: '#/components/responses/documents_UnprocessableEntity'
default:
$ref: '#/components/responses/documents_GenericErrorResponse'
summary: Generate a temporary download link for a document
tags:
- Documents
x-latency-category: responsive
components:
responses:
ListDocServiceDocumentsResponse:
content:
application/json:
schema:
properties:
data:
items:
$ref: '#/components/schemas/DocServiceDocument'
type: array
meta:
$ref: '#/components/schemas/PaginationMeta'
type: object
description: Successful response
documents_UnprocessableEntity:
content:
application/json:
schema:
$ref: '#/components/schemas/documents_Errors'
description: Unprocessable entity. Check the 'detail' field in response for details.
documents_GenericErrorResponse:
content:
application/json:
schema:
$ref: '#/components/schemas/documents_Errors'
description: Unexpected error
ListDocServiceDocumentLinksResponse:
content:
application/json:
schema:
properties:
data:
items:
$ref: '#/components/schemas/DocServiceDocumentLink'
type: array
meta:
$ref: '#/components/schemas/PaginationMeta'
type: object
description: Successful response
ResourceNotFound:
content:
application/json:
schema:
$ref: '#/components/schemas/documents_Error'
description: Resource not found
DocServiceDocumentResponse:
content:
application/json:
schema:
properties:
data:
$ref: '#/components/schemas/DocServiceDocument'
type: object
description: Successful response
DownloadDocServiceDocumentResponse:
content:
'*':
schema:
format: binary
type: string
description: Successful response
parameters:
FilterDocumentLinksConsolidated:
description: 'Consolidated filter parameter for document links (deepObject style). Originally: filter[linked_record_type], filter[linked_resource_id]'
explode: true
in: query
name: filter
required: false
schema:
additionalProperties: false
properties:
linked_record_type:
description: The linked_record_type of the document to filter on.
example: porting_order
type: string
linked_resource_id:
description: The linked_resource_id of the document to filter on.
example: 6a09cdc3-8948-47f0-aa62-74ac943d6c58
format: uuid
type: string
type: object
style: deepObject
Id:
description: Identifies the resource.
in: path
name: id
required: true
schema:
example: 6a09cdc3-8948-47f0-aa62-74ac943d6c58
format: uuid
type: string
SortDocumentsConsolidated:
description: 'Consolidated sort parameter for documents (deepObject style). Originally: sort[]'
in: query
name: sort
required: false
schema:
description: Specifies the sort order for results. If you want to sort by a field in ascending order, include it as a sort parameter. If you want to sort in descending order, prepend a `-` in front of the field name.
example:
- filename
items:
enum:
- filename
- created_at
- updated_at
- -filename
- -created_at
- -updated_at
type: string
type: array
documents_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
FilterDocumentsConsolidated:
description: 'Consolidated filter parameter for documents (deepObject style). Originally: filter[filename][contains], filter[customer_reference][eq], filter[customer_reference][in][], filter[created_at][gt], filter[created_at][lt]'
explode: true
in: query
name: filter
required: false
schema:
additionalProperties: false
example:
created_at:
gt: '2021-01-01T00:00:00Z'
customer_reference:
in:
- REF001
- REF002
filename:
contains: invoice
properties:
created_at:
additionalProperties: false
properties:
gt:
description: Filter by created at greater than provided value.
example: '2021-04-09T22:25:27.521Z'
format: date-time
type: string
lt:
description: Filter by created at less than provided value.
example: '2021-04-09T22:25:27.521Z'
format: date-time
type: string
type: object
customer_reference:
additionalProperties: false
properties:
eq:
description: Filter documents by a customer reference.
example: MY REF 001
type: string
in:
description: Filter documents by a list of customer references.
example:
- MY REF 001
- MY REF 002
items:
type: string
type: array
type: object
filename:
additionalProperties: false
properties:
contains:
description: Filter by string matching part of filename.
example: invoice
type: string
type: object
type: object
style: deepObject
schemas:
DocServiceDocumentLink:
allOf:
- $ref: '#/components/schemas/DocServiceRecord'
- properties:
document_id:
description: Identifies the associated document.
example: 6a09cdc3-8948-47f0-aa62-74ac943d6c58
format: uuid
readOnly: true
type: string
linked_record_type:
description: The linked resource's record type.
example: porting_order
readOnly: true
type: string
linked_resource_id:
description: Identifies the linked resource.
example: 132091b4-442b-4a2a-b87f-61e707e46d54
readOnly: true
type: string
record_type:
description: Identifies the type of the resource.
example: document_link
readOnly: true
type: string
type: object
DocServiceRecord:
properties:
created_at:
description: ISO 8601 formatted date-time indicating when the resource was created.
example: '2018-02-02T22:25:27.521Z'
readOnly: true
type: string
id:
description: Identifies the resource.
example: 6a09cdc3-8948-47f0-aa62-74ac943d6c58
format: uuid
readOnly: true
type: string
record_type:
description: Identifies the type of the resource.
example: sample_record_type
readOnly: true
type: string
updated_at:
description: ISO 8601 formatted date-time indicating when the resource was updated.
example: '2018-02-02T22:25:27.521Z'
readOnly: true
type: string
type: object
CreateMultiPartDocServiceDocumentRequest:
properties:
customer_reference:
description: Optional reference string for customer tracking.
example: MY REF 001
type: string
file:
description: The file you are uploading.
format: binary
type: string
type: object
documents_Error:
properties:
code:
type: string
detail:
type: string
meta:
additionalProperties: true
type: object
source:
properties:
parameter:
description: Indicates which query parameter caused the error.
type: string
pointer:
description: JSON pointer (RFC6901) to the offending entity.
type: string
type: object
title:
type: string
required:
- code
- title
type: object
documents_Errors:
properties:
errors:
items:
$ref: '#/components/schemas/documents_Error'
type: array
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
DocServiceDocument:
allOf:
- $ref: '#/components/schemas/DocServiceRecord'
- properties:
av_scan_status:
description: The antivirus scan status of the document.
enum:
- scanned
- infected
- pending_scan
- not_scanned
example: scanned
readOnly: true
type: string
content_type:
description: The document's content_type.
example: application/pdf
readOnly: true
type: string
customer_reference:
description: Optional reference string for customer tracking.
example: MY REF 001
type: string
filename:
description: The filename of the document.
example: test-document.pdf
type: string
record_type:
description: Identifies the type of the resource.
example: document
readOnly: true
type: string
sha256:
description: The document's SHA256 hash provided for optional verification purposes.
example: 08a96c641c3a74e44eb59afb61a24f2cb9f4d7188748e76ba4bb5edfa3cb7d1c
readOnly: true
type: string
size:
description: Indicates the document's filesize
properties:
amount:
description: The number of bytes
example: 123456
readOnly: true
type: integer
unit:
description: Identifies the unit
example: bytes
readOnly: true
type: string
readOnly: true
type: object
status:
description: Indicates the current document reviewing status
enum:
- pending
- verified
- denied
example: pending
readOnly: true
type: string
type: object
CreateDocServiceDocumentRequest:
properties:
customer_reference:
description: A customer reference string for customer look ups.
example: MY REF 001
type: string
file:
description: Alternatively, instead of the URL you can provide the Base64 encoded contents of the file you are uploading.
example: ZXhhbXBsZSBvZiBlbmNvZGVkIGNvbnRlbnQ=
format: byte
type: string
filename:
description: The filename of the document.
example: test-document.pdf
type: string
url:
description: If the file is already hosted publicly, you can provide a URL and have the documents service fetch it for you.
example: https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf
type: string
type: object
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