openapi: 3.2.0
info:
  version: 2.0.0
  x-latency-category: responsive
  x-endpoint-cost: light
  title: Telnyx Reference Data API
  description: SIP trunking, SMS, MMS, Call Control and Telephony Data Services.
  contact:
    email: support@telnyx.com
servers:
- url: https://api.telnyx.com/v2
  description: Version 2.0.0 of the Telnyx API
security:
- bearerAuth: []
tags:
- name: Reference Data
  description: 'Static reference values the API accepts: call reasons, document types, rejection types.'
paths:
  /call_reasons:
    get:
      summary: List standard call reasons
      description: Telnyx maintains a library of pre-vetted call-reason phrases (e.g. "Appointment reminders", "Billing inquiries") that carry through DIR vetting smoothly. You can use any string that fits your use case in `DirCreateRequest.call_reasons`, but matching one of these reduces the chance the vetting team flags the phrasing for clarification.
      operationId: listCallReasons
      tags:
      - Reference Data
      parameters:
      - $ref: '#/components/parameters/BcPageNumber'
      - name: page[size]
        in: query
        required: false
        description: Items per page. Default `100` for this endpoint (the call-reason library is small and most callers want the whole list in one call). Maximum 250; values above are clamped to 250.
        schema:
          type: integer
          minimum: 1
          maximum: 250
          default: 100
          example: 100
      responses:
        '200':
          description: Paginated list of standard call reasons.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CallReasonReferenceList'
              example:
                data:
                - id: d29914a4-3c93-440c-af72-03778f442522
                  reason: Account Alert
                  description: Alert about account status or changes
                - id: 4cabcae2-6c61-415b-ac5b-753469458a56
                  reason: Account Notification
                  description: General account notifications
                meta:
                  page_number: 1
                  page_size: 2
                  total_results: 45
                  total_pages: 23
        default:
          $ref: '#/components/responses/branded-calling_GenericErrorResponse'
        4XX:
          $ref: '#/components/responses/branded-calling_GenericErrorResponse'
  /call_reasons/validate:
    post:
      summary: Validate a list of call reasons
      description: Check up to 10 candidate `call_reasons` strings against Telnyx's vetting heuristics before sending them on a DIR create or update. The endpoint flags strings that are likely to be rejected during vetting (too generic, banned phrases, length issues, etc.) so you can fix them up front.
      operationId: validateCallReasons
      tags:
      - Reference Data
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ValidateCallReasonsRequest'
            example:
            - Appointment reminders
            - Billing inquiries
      responses:
        '200':
          description: Per-string validation result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidateCallReasonsResponse'
        default:
          $ref: '#/components/responses/branded-calling_GenericErrorResponse'
        4XX:
          $ref: '#/components/responses/branded-calling_GenericErrorResponse'
  /dir/document_types:
    get:
      summary: List supported DIR document types
      description: Reference list of `document_type` values accepted by `DirCreateRequest.documents[].document_type` and the infringement-contest endpoint. Each entry has a stable `short_name` (used in API calls) and a customer-facing description.
      operationId: listDocumentTypes
      tags:
      - Reference Data
      responses:
        '200':
          description: List of supported document types.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentTypeReferenceList'
              example:
                data:
                - short_name: letter_of_authorization
                  description: Signed authorization from the DIR owner permitting Telnyx to register the DIR and its associated numbers on their behalf
                - short_name: business_registration
                  description: Official Secretary of State (or equivalent) registration showing the legal entity exists and is in good standing
                meta:
                  total_pages: 1
                  total_results: 2
                  page_number: 1
                  page_size: 20
        default:
          $ref: '#/components/responses/branded-calling_GenericErrorResponse'
        4XX:
          $ref: '#/components/responses/branded-calling_GenericErrorResponse'
components:
  schemas:
    CallReasonReference:
      type: object
      description: Pre-vetted call-reason library entry.
      properties:
        id:
          type: string
          format: uuid
          example: d29914a4-3c93-440c-af72-03778f442522
          readOnly: true
        reason:
          type: string
          example: Account Alert
        description:
          type: string
          example: Alert about account status or changes
    ValidateCallReasonsResponse:
      type: object
      required:
      - data
      properties:
        data:
          type: object
          required:
          - all_pre_approved
          - non_approved_reasons
          - requires_manual_vetting
          properties:
            all_pre_approved:
              type: boolean
              description: '`true` when every supplied reason matches a pre-vetted entry in the call-reason library. When `true`, the DIR will sail through the call-reasons portion of vetting.'
              example: false
            non_approved_reasons:
              type: array
              items:
                type: string
              description: Subset of the input that does NOT match the pre-vetted library. The DIR can still be submitted with these - they will go through manual review.
              example:
              - Appointment reminders
              - Billing inquiries
            requires_manual_vetting:
              type: boolean
              description: '`true` when at least one supplied reason is in `non_approved_reasons`. Equivalent to `non_approved_reasons.length > 0` and the inverse of `all_pre_approved`.'
              example: true
    DocumentTypeReference:
      type: object
      description: Single supported document type.
      properties:
        short_name:
          type: string
          description: Stable identifier passed to `Document.document_type`.
          example: letter_of_authorization
        description:
          type: string
          example: Signed authorization from the DIR owner permitting Telnyx to register the DIR and its associated numbers on their behalf
    branded-calling_PaginationMeta:
      type: object
      required:
      - total_pages
      - total_results
      - page_number
      - page_size
      properties:
        total_pages:
          type: integer
          example: 3
          description: Total number of pages available given the current `page_size`.
        total_results:
          type: integer
          example: 42
          description: Total number of items across all pages (excludes soft-deleted rows).
        page_number:
          type: integer
          example: 1
          description: 1-based index of this page. Echoes the `page[number]` query parameter (default `1`).
        page_size:
          type: integer
          example: 20
          description: Number of items returned in this page's `data` array. Capped at 250.
      description: JSON:API pagination metadata returned with every paginated list response. Page numbering is 1-based. `page_size` reports the number of items actually returned in `data` for this page; the requested size is taken from the `page[size]` query parameter.
    DocumentTypeReferenceList:
      type: object
      required:
      - data
      - meta
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/DocumentTypeReference'
        meta:
          $ref: '#/components/schemas/branded-calling_PaginationMeta'
    CallReasonReferenceList:
      type: object
      required:
      - data
      - meta
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/CallReasonReference'
        meta:
          $ref: '#/components/schemas/branded-calling_PaginationMeta'
    ValidateCallReasonsRequest:
      type: array
      description: '**Bare JSON array** of candidate call-reason strings (NOT an object - there is no top-level `call_reasons` key on this endpoint). 1–10 strings, each ≤64 characters.'
      items:
        type: string
        maxLength: 64
      minItems: 1
      maxItems: 10
      example:
      - Appointment reminders
      - Billing inquiries
    branded-calling_Errors:
      type: object
      required:
      - errors
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/branded-calling_Error'
          description: List of one or more error entries. Order is not significant.
      description: Canonical Telnyx error envelope. Returned on every 4xx and 5xx response from this service. `errors` is non-empty; multiple entries indicate multiple distinct problems with the same request (e.g. one entry per invalid phone number on a bulk operation).
    branded-calling_Error:
      type: object
      required:
      - code
      - title
      - detail
      - meta
      properties:
        code:
          type: string
          example: '10005'
          description: Stable numeric Telnyx error catalog id. See `meta.url` for the full catalog entry.
        title:
          type: string
          example: Invalid parameters
          description: Short human-readable category, e.g. `Bad Request`, `Duplicate resource`, `Not Found`, `Forbidden`. Treat as advisory only - the stable identifier is `code`.
        detail:
          type: string
          example: field required
          description: Context-specific message describing what went wrong on this particular request. May embed offending values; do not rely on it for programmatic matching - branch on `code`.
        meta:
          type: object
          required:
          - url
          properties:
            url:
              type: string
              format: uri
              example: https://developers.telnyx.com/docs/overview/errors/10005
            pending_check_ids:
              type: array
              items:
                type: string
                format: uuid
              description: Set on `422 vetting_checks_incomplete` responses from `/admin/dir/{id}/approve` and `/admin/phone-number-batches/approve`. Lists the still-pending vetting check ids.
            pending_check_codes:
              type: array
              items:
                type: string
              description: Codes of the pending vetting checks (e.g. `loa_signature_valid`).
            pending_check_labels:
              type: array
              items:
                type: string
              description: Human-readable labels of the pending vetting checks.
          description: Carries `url` linking to the Telnyx error catalog entry for this `code`. Useful for forwarding the user to documentation.
        source:
          type: object
          description: Optional pointer at the offending field of the request.
          properties:
            pointer:
              type: string
              example: /body/legal_name
            parameter:
              type: string
              example: page[size]
      description: A single entry in the canonical Telnyx error envelope. `code` is the stable Telnyx error catalog id; the human-readable explanation lives at `meta.url`. `detail` is a context-specific message; `source.pointer` (when present) names the offending field of the request.
  responses:
    branded-calling_GenericErrorResponse:
      description: An error occurred. The response carries the standard Telnyx error envelope.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/branded-calling_Errors'
          examples:
            validation_error:
              summary: 422 - request body failed validation
              value:
                errors:
                - code: '10005'
                  title: Invalid parameters
                  detail: field required
                  meta:
                    url: https://developers.telnyx.com/docs/overview/errors/10005
                  source:
                    pointer: /body/legal_name
            bad_request:
              summary: 400 - request rejected by a state guard
              description: Returned when the request itself is well-formed but the resource is in a state that disallows this action (e.g. updating a DIR while it is being vetted, or deleting an enterprise that still has DIRs in vetting).
              value:
                errors:
                - code: '10015'
                  title: Bad Request
                  detail: Cannot update DIR in 'verified' status
                  meta:
                    url: https://developers.telnyx.com/docs/overview/errors/10015
            not_found:
              summary: 404 - resource does not exist or is not yours
              value:
                errors:
                - code: '10009'
                  title: Resource not found
                  detail: Enterprise not found.
                  meta:
                    url: https://developers.telnyx.com/docs/overview/errors/10009
            conflict:
              summary: 409 - request conflicts with current resource state
              value:
                errors:
                - code: '10021'
                  title: Resource in use
                  detail: DIR has 1 active infringement claim(s). Resolve the claim before making this change.
                  meta:
                    url: https://developers.telnyx.com/docs/overview/errors/10021
  parameters:
    BcPageNumber:
      name: page[number]
      in: query
      description: 1-based page number. Out-of-range values return an empty page with correct meta.
      required: false
      schema:
        type: integer
        minimum: 1
        default: 1
        example: 1
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key
      description: 'Telnyx API key supplied as `Authorization: Bearer <token>`. In production, auth may be validated by the API gateway and forwarded via Telnyx auth headers.'
    Payment:
      type: apiKey
      in: header
      name: Authorization
      description: 'Machine Payment Protocol credential used on paid retries, sent as `Authorization: Payment ...`. Obtained by paying a challenge returned in the `WWW-Authenticate` header of a 402 response. This is not a Telnyx API key; initial challenge requests use standard bearer authentication instead.'
    agent-memory_bearerAuth:
      type: http
      scheme: bearer
      description: Telnyx API key
    bearerAuth:
      type: http
      scheme: bearer
    branded-calling_bearerAuth:
      type: http
      scheme: bearer
      description: Telnyx API key. Generate one at https://portal.telnyx.com/#/app/api-keys.
    collections_bearerAuth:
      type: http
      scheme: bearer
      description: Telnyx API key. Collections and results are automatically scoped to the authenticated user's organization.
    number-reputation_bearerAuth:
      type: http
      scheme: bearer
      description: Telnyx API key. Generate one at https://portal.telnyx.com/#/app/api-keys.
    oauthClientAuth:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://api.telnyx.com/v2/oauth/token
          scopes:
            admin: Administrative access to Telnyx resources
        authorizationCode:
          authorizationUrl: https://api.telnyx.com/v2/oauth/authorize
          tokenUrl: https://api.telnyx.com/v2/oauth/token
          refreshUrl: https://api.telnyx.com/v2/oauth/token
          scopes:
            admin: Administrative access to Telnyx resources
      description: OAuth 2.0 authentication for Telnyx API and MCP integrations
    outbound-voice-profiles_bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    pronunciation-dicts_bearerAuth:
      type: http
      scheme: bearer
      description: Telnyx API v2 key. Obtain from https://portal.telnyx.com
    rcs-registration_bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key
    stored-payment-transactions_bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    transcriptions-search_bearerAuth:
      type: http
      scheme: bearer
      description: Telnyx API key. Results are automatically scoped to the authenticated user's organization.
    web-search_bearerAuth:
      type: http
      scheme: bearer
      description: Telnyx API key
x-service-info:
  categories:
  - communication
  - developer-tools
  docs:
    apiReference: https://developers.telnyx.com
    homepage: https://telnyx.com
    llms: https://telnyx.com/llms.txt