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 Phone Number Orders 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: Number orders
  name: Phone Number Orders
paths:
  /comments:
    get:
      operationId: ListComments
      parameters:
      - description: 'Consolidated filter parameter (deepObject style). Originally: filter[comment_record_type], filter[comment_record_id]'
        explode: true
        in: query
        name: filter
        schema:
          properties:
            comment_record_id:
              description: ID of the record the comments relate to
              example: 8ffb3622-7c6b-4ccc-b65f-7a3dc0099576
              type: string
            comment_record_type:
              description: Record type that the comment relates to
              enum:
              - sub_number_order
              - requirement_group
              example: sub_number_order
              type: string
          type: object
        style: deepObject
      responses:
        '200':
          $ref: '#/components/responses/listCommentsResponse'
        '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: Retrieve all comments
      tags:
      - Phone Number Orders
      x-latency-category: responsive
    post:
      operationId: CreateComment
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Comment'
        required: true
      responses:
        '200':
          $ref: '#/components/responses/CommentResponse'
        '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: Create a comment
      tags:
      - Phone Number Orders
      x-latency-category: responsive
  /comments/{id}:
    get:
      operationId: RetrieveComment
      parameters:
      - description: The comment ID.
        in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        '200':
          $ref: '#/components/responses/CommentResponse'
        '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: Retrieve a comment
      tags:
      - Phone Number Orders
      x-latency-category: responsive
  /comments/{id}/read:
    patch:
      operationId: MarkCommentRead
      parameters:
      - description: The comment ID.
        in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        '200':
          $ref: '#/components/responses/ReadCommentResponse'
        '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: Mark a comment as read
      tags:
      - Phone Number Orders
      x-latency-category: responsive
  /number_order_phone_numbers:
    get:
      description: Get a list of phone numbers associated to orders.
      operationId: RetrieveOrderPhoneNumbers
      parameters:
      - description: 'Consolidated filter parameter (deepObject style). Originally: filter[country_code]'
        explode: true
        in: query
        name: filter
        schema:
          properties:
            country_code:
              description: Country code of the order phone number.
              example: US
              type: string
          type: object
        style: deepObject
      responses:
        '200':
          $ref: '#/components/responses/ListNumberOrderPhoneNumbersResponse'
        '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: Retrieve a list of phone numbers associated to orders
      tags:
      - Phone Number Orders
      x-latency-category: responsive
  /number_order_phone_numbers/{number_order_phone_number_id}:
    get:
      description: Get an existing phone number in number order.
      operationId: GetNumberOrderPhoneNumber
      parameters:
      - description: The number order phone number ID.
        in: path
        name: number_order_phone_number_id
        required: true
        schema:
          type: string
      responses:
        '200':
          $ref: '#/components/responses/NumberOrderPhoneNumberResponse'
        '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: Retrieve a single phone number within a number order.
      tags:
      - Phone Number Orders
      x-latency-category: responsive
    patch:
      description: Updates requirements for a single phone number within a number order.
      operationId: UpdateNumberOrderPhoneNumber
      parameters:
      - description: The number order phone number ID.
        in: path
        name: number_order_phone_number_id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateNumberOrderPhoneNumberRequest'
        required: true
      responses:
        '200':
          $ref: '#/components/responses/NumberOrderPhoneNumberResponse'
        '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 requirements for a single phone number within a number order.
      tags:
      - Phone Number Orders
      x-latency-category: responsive
  /number_orders:
    get:
      description: Get a paginated list of number orders.
      operationId: ListNumberOrders
      parameters:
      - $ref: '#/components/parameters/numbers_PageConsolidated'
      - description: 'Consolidated filter parameter (deepObject style). Originally: filter[status], filter[created_at], filter[phone_numbers_count], filter[customer_reference], filter[requirements_met]'
        explode: true
        in: query
        name: filter
        schema:
          properties:
            created_at:
              additionalProperties: false
              description: Filter number orders by date range.
              properties:
                gt:
                  description: Filter number orders later than this value.
                  type: string
                lt:
                  description: Filter number orders earlier than this value.
                  type: string
              type: object
            customer_reference:
              description: Filter number orders via the customer reference set.
              type: string
            phone_numbers_count:
              description: Filter number order with this amount of numbers
              type: string
            requirements_met:
              description: Filter number orders by requirements met.
              type: boolean
            status:
              description: Filter number orders by status.
              type: string
          type: object
        style: deepObject
      responses:
        '200':
          $ref: '#/components/responses/ListNumberOrdersResponse'
        '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: List number orders
      tags:
      - Phone Number Orders
      x-endpoint-cost: medium
      x-group-parameters: 'true'
      x-latency-category: responsive
    post:
      description: Creates a phone number order.
      operationId: CreateNumberOrder
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateNumberOrderRequest'
        required: true
      responses:
        '200':
          $ref: '#/components/responses/NumberOrderResponse'
        '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: Create a number order
      tags:
      - Phone Number Orders
      x-endpoint-cost: heavy
      x-latency-category: responsive
  /number_orders/{number_order_id}:
    get:
      description: Get an existing phone number order.
      operationId: RetrieveNumberOrder
      parameters:
      - description: The number order ID.
        in: path
        name: number_order_id
        required: true
        schema:
          type: string
      responses:
        '200':
          $ref: '#/components/responses/NumberOrderResponse'
        '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: Retrieve a number order
      tags:
      - Phone Number Orders
      x-latency-category: responsive
    patch:
      description: Updates a phone number order.
      operationId: UpdateNumberOrder
      parameters:
      - description: The number order ID.
        in: path
        name: number_order_id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateNumberOrderRequest'
        required: true
      responses:
        '200':
          $ref: '#/components/responses/NumberOrderResponse'
        '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 a number order
      tags:
      - Phone Number Orders
      x-latency-category: responsive
  /sub_number_orders:
    get:
      description: Get a paginated list of sub number orders.
      operationId: ListSubNumberOrders
      parameters:
      - description: 'Consolidated filter parameter (deepObject style). Originally: filter[status], filter[order_request_id], filter[country_code], filter[phone_number_type], filter[phone_numbers_count]'
        explode: true
        in: query
        name: filter
        schema:
          properties:
            country_code:
              description: ISO alpha-2 country code.
              example: US
              type: string
            order_request_id:
              description: ID of the number order the sub number order belongs to
              example: 12ade33a-21c0-473b-b055-b3c836e1c293
              format: uuid
              type: string
            phone_number_type:
              description: Phone Number Type
              example: local
              type: string
            phone_numbers_count:
              description: Amount of numbers in the sub number order
              example: 1
              type: integer
            status:
              description: Filter sub number orders by status.
              type: string
          type: object
        style: deepObject
      responses:
        '200':
          $ref: '#/components/responses/ListSubNumberOrdersResponse'
        '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: List sub number orders
      tags:
      - Phone Number Orders
      x-group-parameters: 'true'
      x-latency-category: responsive
  /sub_number_orders/{sub_number_order_id}:
    get:
      description: Get an existing sub number order.
      operationId: GetSubNumberOrder
      parameters:
      - description: The sub number order ID.
        in: path
        name: sub_number_order_id
        required: true
        schema:
          type: string
      - description: 'Consolidated filter parameter (deepObject style). Originally: filter[include_phone_numbers]'
        explode: true
        in: query
        name: filter
        schema:
          properties:
            include_phone_numbers:
              default: false
              description: Include the first 50 phone number objects in the results
              type: boolean
          type: object
        style: deepObject
      responses:
        '200':
          $ref: '#/components/responses/SubNumberOrderResponse'
        '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: Retrieve a sub number order
      tags:
      - Phone Number Orders
      x-latency-category: responsive
    patch:
      description: Updates a sub number order.
      operationId: UpdateSubNumberOrder
      parameters:
      - description: The sub number order ID.
        in: path
        name: sub_number_order_id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateSubNumberOrderRequest'
        required: true
      responses:
        '200':
          $ref: '#/components/responses/SubNumberOrderResponse'
        '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 a sub number order's requirements
      tags:
      - Phone Number Orders
      x-latency-category: responsive
  /sub_number_orders/{sub_number_order_id}/cancel:
    patch:
      description: Allows you to cancel a sub number order in 'pending' status.
      operationId: CancelSubNumberOrder
      parameters:
      - description: The ID of the sub number order.
        in: path
        name: sub_number_order_id
        required: true
        schema:
          type: string
      responses:
        '200':
          $ref: '#/components/responses/SubNumberOrderResponse'
        '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: Cancel a sub number order
      tags:
      - Phone Number Orders
      x-latency-category: responsive
  /sub_number_orders_report:
    post:
      description: Create a CSV report for sub number orders. The report will be generated asynchronously and can be downloaded once complete.
      operationId: CreateSubNumberOrdersReport
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSubNumberOrdersReportRequest'
        required: false
      responses:
        '202':
          $ref: '#/components/responses/SubNumberOrdersReportResponse'
        '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 sub number orders report
      tags:
      - Phone Number Orders
      x-endpoint-cost: medium
      x-latency-category: background
  /sub_number_orders_report/{report_id}:
    get:
      description: Get the status and details of a sub number orders report.
      operationId: GetSubNumberOrdersReport
      parameters:
      - description: The unique identifier of the sub number orders report
        example: 12ade33a-21c0-473b-b055-b3c836e1c293
        in: path
        name: report_id
        required: true
        schema:
          format: uuid
          type: string
      responses:
        '200':
          $ref: '#/components/responses/SubNumberOrdersReportResponse'
        '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: Retrieve a sub number orders report
      tags:
      - Phone Number Orders
      x-endpoint-cost: light
      x-latency-category: responsive
  /sub_number_orders_report/{report_id}/download:
    get:
      description: Download the CSV file for a completed sub number orders report. The report status must be 'success' before the file can be downloaded.
      operationId: DownloadSubNumberOrdersReport
      parameters:
      - description: The unique identifier of the sub number orders report
        example: 12ade33a-21c0-473b-b055-b3c836e1c293
        in: path
        name: report_id
        required: true
        schema:
          format: uuid
          type: string
      responses:
        '200':
          content:
            text/csv:
              example: 'id,order_request_id,is_block_sub_number_order,status,phone_number_type,requirements_met,phone_numbers_count,country_code,user_id,customer_reference,created_at,updated_at

                1758d6ed-61a0-4d7a-bf57-b5dced413d33,f486fc2c-4fdf-4849-930d-b3045373e839,False,success,local,True,1,US,0d7ef697-df19-413a-b724-56b0539f5397,STRING,2025-05-23 14:33:12.376686,2025-05-23 14:33:15.624916'
              schema:
                format: binary
                type: string
          description: CSV file download
        '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: Download a sub number orders report
      tags:
      - Phone Number Orders
      x-endpoint-cost: light
      x-latency-category: background
components:
  parameters:
    numbers_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
  responses:
    numbers_UnprocessableEntity:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/numbers_Errors'
      description: Unprocessable entity. Check the 'detail' field in response for details.
    SubNumberOrdersReportResponse:
      content:
        application/json:
          schema:
            properties:
              data:
                $ref: '#/components/schemas/SubNumberOrdersReport'
            type: object
      description: Sub number orders report response
    ListNumberOrdersResponse:
      content:
        application/json:
          schema:
            properties:
              data:
                items:
                  $ref: '#/components/schemas/NumberOrder'
                type: array
              meta:
                $ref: '#/components/schemas/PaginationMeta'
            title: List Number Orders Response
            type: object
      description: Successful response with a list of number orders.
    SubNumberOrderResponse:
      content:
        application/json:
          schema:
            properties:
              data:
                $ref: '#/components/schemas/SubNumberOrder'
            title: Sub Number Order Response
            type: object
      description: Successful response with details about a sub number order.
    ListNumberOrderPhoneNumbersResponse:
      content:
        application/json:
          schema:
            properties:
              data:
                items:
                  $ref: '#/components/schemas/NumberOrderPhoneNumber'
                type: array
              meta:
                $ref: '#/components/schemas/PaginationMeta'
            title: List Number Order Phone Numbers Response
            type: object
      description: Successful response with a list of number order phone numbers.
    CommentResponse:
      content:
        application/json:
          schema:
            properties:
              data:
                allOf:
                - $ref: '#/components/schemas/Comment'
                - type: object
            type: object
      description: A Comment Response
    ReadCommentResponse:
      content:
        application/json:
          schema:
            properties:
              data:
                allOf:
                - $ref: '#/components/schemas/ReadComment'
                - type: object
            type: object
      description: A Comment Response
    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_NotFoundResponse:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/numbers_Errors'
      description: The requested resource doesn't exist.
    ListSubNumberOrdersResponse:
      content:
        application/json:
          schema:
            properties:
              data:
                items:
                  $ref: '#/components/schemas/SubNumberOrder'
                type: array
              meta:
                $ref: '#/components/schemas/PaginationMeta'
            title: List Sub Number Orders Response
            type: object
      description: Successful response with a list of sub number orders.
    NumberOrderPhoneNumberResponse:
      content:
        application/json:
          schema:
            properties:
              data:
                $ref: '#/components/schemas/NumberOrderPhoneNumber'
            title: Number Order Phone Number Response
            type: object
      description: Successful response with details about a number order phone number.
    listCommentsResponse:
      content:
        application/json:
          schema:
            properties:
              data:
                items:
                  $ref: '#/components/schemas/Comment'
                type: array
              meta:
                $ref: '#/components/schemas/PaginationMeta'
            type: object
      description: An array of Comment Responses
    numbers_GenericErrorResponse:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/numbers_Errors'
      description: Unexpected error
    NumberOrderResponse:
      content:
        application/json:
          schema:
            properties:
              data:
                $ref: '#/components/schemas/NumberOrderWithPhoneNumbers'
            title: Number Order Response
            type: object
      description: Successful response with details about a number order.
    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.
  schemas:
    SubNumberOrderRegulatoryRequirement:
      properties:
        field_type:
          enum:
          - textual
          - datetime
          - address
          - document
          example: address
          readOnly: true
          type: string
        record_type:
          example: phone_number_regulatory_requirement
          readOnly: true
          type: string
        requirement_id:
          description: Unique id for a requirement.
          example: 8ffb3622-7c6b-4ccc-b65f-7a3dc0099576
          format: uuid
          type: string
      type: object
    Comment:
      properties:
        body:
          example: Hi there, ....
          type: string
        comment_record_id:
          example: 8ffb3622-7c6b-4ccc-b65f-7a3dc0099576
          format: uuid
          type: string
        comment_record_type:
          enum:
          - sub_number_order
          - requirement_group
          example: sub_number_order
          type: string
        commenter:
          example: user@company.com
          readOnly: true
          type: string
        commenter_type:
          enum:
          - admin
          - user
          example: user
          readOnly: true
          type: string
        created_at:
          description: An ISO 8901 datetime string denoting when the comment was created.
          example: '2018-01-01T00:00:00.000000Z'
          format: date-time
          readOnly: true
          type: string
        id:
          example: 12ade33a-21c0-473b-b055-b3c836e1c292
          format: uuid
          readOnly: true
          type: string
        read_at:
          description: An ISO 8901 datetime string for when the comment was read.
          example: '2018-01-01T00:00:00.000000Z'
          format: date-time
          readOnly: true
          type: string
        updated_at:
          description: An ISO 8901 datetime string for when the comment was updated.
          example: '2018-01-01T00:00:00.000000Z'
          format: date-time
          readOnly: true
          type: string
      type: object
    NumberOrderPhoneNumber:
      properties:
        bundle_id:
          example: a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d
          format: uuid
          readOnly: true
          type:
          - string
          - 'null'
        country_code:
          example: US
          type: string
        deadline:
          example: '2024-05-31T11:14:00Z'
          format: date-time
          type: string
        id:
          example: dc8e4d67-33a0-4cbb-af74-7b58f05bd494
          format: uuid
          readOnly: true
          type: string
        is_block_number:
          example: false
          type: boolean
        locality:
          example: San Francisco
          type: string
        order_request_id:
          example: dc8e4d67-33a0-4cbb-af74-7b58f05bd495
          format: uuid
          type: string
        phone_number:
          example: '+19705555098'
          type: string
        phone_number_type:
          enum:
          - local
          - toll_free
          - mobile
          - national
          - shared_cost
          - landline
          example: local
          type: string
        record_type:
          example: number_order_phone_number
          readOnly: true
          type: string
        regulatory_requirements:
          items:
            $ref: '#/components/schemas/SubNumberOrderRegulatoryRequirementWithValue'
          type: array
        requirements_met:
          description: True if all requirements are met for a phone number, false otherwise.
          example: true
          readOnly: true
          type: boolean
        requirements_status:
          description: Status of requirements (if applicable)
          enum:
          - pending
          - approved
          - cancelled
          - deleted
          - requirement-info-exception
          - requirement-info-pending
          - requirement-info-under-review
          readOnly: true
          type: string
        status:
          description: The status of the phone number in the order.
          enum:
          - pending
          - success
          - failure
          readOnly: true
          type: string
        sub_number_order_id:
          example: dc8e4d67-33a0-4cbb-af74-7b58f05bd496
          format: uuid
          type: string
      type: object
    NumberOrder:
      properties:
        billing_group_id:
          description: Identifies the messaging profile associated with the phone number.
          example: abc85f64-5717-4562-b3fc-2c9600
          type: string
        connection_id:
          description: Identifies the connection associated with this phone number.
          example: '346789098765567'
          type: string
        created_at:
          description: An ISO 8901 datetime string denoting when the number order was created.
          example: '2018-01-01T00:00:00.000000Z'
          format: date-time
          readOnly: true
          type: string
        customer_reference:
          description: A customer reference string for customer look ups.
          example: MY REF 001
          type: string
        id:
          example: 12ade33a-21c0-473b-b055-b3c836e1c292
          format: uuid
          readOnly: true
          type: string
        messaging_profile_id:
          description: Identifies the messaging profile associated with the phone number.
          example: abc85f64-5717-4562-b3fc-2c9600
          type: string
        phone_numbers:
          items:
            $ref: '#/components/schemas/PhoneNumbersJobPhoneNumber'
            description: The unique phone numbers given as arguments in the job creation.
          type: array
        phone_numbers_count:
          description: The count of phone numbers in the number order.
          example: 1
          readOnly: true
          type: integer
        record_type:
          example: number_order
          readOnly: true
          type: string
        requirements_met:
          description: True if all requirements are met for every phone number, false otherwise.
          example: true
          readOnly: true
          type: boolean
        status:
          description: The status of the order.
          enum:
          - pending
          - success
          - failure
          readOnly: true
          type: string
        sub_number_orders_ids:
          items:
            type: string
          type: array
        updated_at:
          description: An ISO 8901 datetime string for when the number order was updated.
          example: '2018-01-01T00:00:00.000000Z'
          format: date-time
          readOnly: true
          type: string
      title: Number Order With Phone Numbers
      type: object
    PhoneNumber:
      example:
        bundle_id: bc8e4d67-33a0-4cbb-af74-7b58f05bd474
        id: dc8e4d67-33a0-4cbb-af74-7b58f05bd494
        phone_number: '+19705555098'
        record_type: number_order_phone_number
        regulatory_requirements:
        - field_type: address
          field_value: 45f45a04-b4be-4592-95b1-9306b9db2b21
          record_type: phone_number_regulatory_requirement
          requirement_id: 8ffb3622-7c6b-4ccc-b65f-7a3dc0099576
        requirements_met: true
        status: success
      properties:
        bundle_id:
          example: bc8e4d67-33a0-4cbb-af74-7b58f05bd494
          format: uuid
          readOnly: true
          type: string
        country_code:
          description: Country code of the phone number
          example: US
          readOnly: true
          type: string
        country_iso_alpha2:
          description: The ISO 3166-1 alpha-2 country code of the phone number.
          example: US
          readOnly: true
          type: string
        id:
          example: dc8e4d67-33a0-4cbb-af74-7b58f05bd494
          format: uuid
          readOnly: true
          type: string
        phone_number:
          example: '+19705555098'
          type: string
        phone_number_type:
          description: Phone number type
          enum:
          - local
          - mobile
          - national
          - shared_cost
          - toll_free
          readOnly: true
          type: string
        record_type:
          example: number_order_phone_number
          readOnly: true
          type: string
        regulatory_requirements:
          items:
            $ref: '#/components/schemas/SubNumberOrderRegulatoryRequirementWithValue'
          type: array
        requirements_met:
          description: True if all requirements are met for a phone number, false otherwise.
          example: true
          readOnly: true
          type: boolean
        requirements_status:
          description: Status of document requirements (if applicable)
          enum:
          - pending
          - approved
          - cancelled
          - deleted
          - requirement-info-exception
          - requirement-info-pending
          - requirement-info-under-review
          readOnly: true
          type: string
        status:
          description: The status of the phone number in the order.
          enum:
          - pending
          - success
          - failure
          readOnly: true
          type: string
      type: object
    UpdateNumberOrderRequest:
      properties:
        customer_reference:
          description: A customer reference string for customer look ups.
          example: MY REF 001
          type: string
        regulatory_requirements:
          items:
            $ref: '#/components/schemas/UpdateRegulatoryRequirement'
          type: array
      type: object
    ReadComment:
      $ref: '#/components/schemas/Comment'
    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
    UpdateNumberOrderPhoneNumberRequest:
      properties:
        regulatory_requirements:
          items:
            $ref: '#/components/schemas/UpdateRegulatoryRequirement'
          type: array
      type: object
    NumberOrderWithPhoneNumbers:
      properties:
        billing_group_id:
          description: Identifies the messaging profile associated with the phone number.
          example: abc85f64-5717-4562-b3fc-2c9600
          type: string
        connection_id:
          description: Identifies the connection associated with this phone number.
          example: '346789098765567'
          type: string
        created_at:
          description: An ISO 8901 datetime string denoting when the number order was created.
          example: '2018-01-01T00:00:00.000000Z'
          format: date-time
          readOnly: true
          type: string
        customer_reference:
          description: A customer reference string for customer look ups.
          example: MY REF 001
          type: string
        id:
          example: 12ade33a-21c0-473b-b055-b3c836e1c292
          format: uuid
          readOnly: true
          type: string
        messaging_profile_id:
          description: Identifies the messaging profile associated with the phone number.
          example: abc85f64-5717-4562-b3fc-2c9600
          type: string
        phone_numbers:
          items:
            $ref: '#/components/schemas/PhoneNumber'
            description: The unique phone numbers given as arguments in the job creation.
          type: array
        phone_numbers_count:
          description: The count of phone numbers in the number order.
          example: 1
          readOnly: true
          type: integer
        record_type:
          example: number_order
          readOnly: true
          type: string
        requirements_met:
          description: True if all requirements are met for every phone number, false otherwise.
          example: true
          readOnly: true
          type: boolean
        status:
          description: The status of the order.
          enum:
          - pending
          - success
          - failure
          readOnly: true
          type: string
        sub_number_orders_ids:
          items:
            type: string
          type: array
        updated_at:
          description: An ISO 8901 datetime string for when the number order was updated.
          example: '2018-01-01T00:00:00.000000Z'
          format: date-time
          readOnly: true
          type: string
      title: NumberOrder
      type: object
    UpdateRegulatoryRequirement:
      properties:
        field_value:
          description: The value of the requirement. For address and document requirements, this should be the ID of the resource. For textual, this should be the value of the requirement.
          example: 45f45a04-b4be-4592-95b1-9306b9db2b21
          type: string
        requirement_id:
          description: Unique id for a requirement.
          example: 8ffb3622-7c6b-4ccc-b65f-7a3dc0099576
          format: uuid
          type: string
      type: object
    CreateNumberOrderRequest:
      example:
        billing_group_id: abc85f64-5717-4562-b3fc-2c9600
        connection_id: '346789098765567'
        customer_reference: MY REF 001
        messaging_profile_id: abc85f64-5717-4562-b3fc-2c9600
        phone_numbers:
        - bundle_id: bc8e4d67-33a0-4cbb-af74-7b58f05bd494
          phone_number: '+19705555098'
        - phone_number: '+492111609539'
          requirement_group_id: dbbd94ee-9079-488f-80ba-f566b247fd79
      properties:
        billing_group_id:
          description: Identifies the billing group associated with the phone number.
          example: abc85f64-5717-4562-b3fc-2c9600
          type: string
        connection_id:
          description: Identifies the connection associated with this phone number.
          example: '346789098765567'
          type: string
        customer_reference:
          description: A customer reference string for customer look ups.
          example: MY REF 001
          type: string
        messaging_profile_id:
          description: Identifies the messaging profile associated with the phone number.
          example: abc85f64-5717-4562-b3fc-2c9600
          type: string
        phone_numbers:
          items:
            properties:
              bundle_id:
                description: ID of bundle to associate the number to
                example: bc8e4d67-33a0-4cbb-af74-7b58f05bd494
                type: string
              phone_number:
                description: e164_phone_number
                example: '+19705555098'
                type: string
              requirement_group_id:
                description: ID of requirement group to use to satisfy number requirements
                example: dbbd94ee-9079-488f-80ba-f566b247fd7
                type: string
            required:
            - phone_number
            type: object
          type: array
          writeOnly: true
      type: object
    CreateSubNumberOrdersReportRequest:
      example:
        country_code: US
        created_at_gt: '2023-04-05T10:22:08.230549Z'
        created_at_lt: '2025-06-05T10:22:08.230549Z'
        customer_reference: STRING
        order_request_id: 12ade33a-21c0-473b-b055-b3c836e1c293
        status: success
      properties:
        country_code:
          description: Filter by country code
          example: US
          type: string
        created_at_gt:
          description: Filter for orders created after this date
          example: '2023-04-05T10:22:08.230549Z'
          format: date-time
          type: string
        created_at_lt:
          description: Filter for orders created before this date
          example: '2025-06-05T10:22:08.230549Z'
          format: date-time
          type: string
        customer_reference:
          description: Filter by customer reference
          example: STRING
          type: string
        order_request_id:
          description: Filter by specific order request ID
          example: 12ade33a-21c0-473b-b055-b3c836e1c293
          format: uuid
          type: string
        status:
          description: Filter by order status
          enum:
          - pending
          - success
          - failure
          example: success
          type: string
      type: object
    numbers_Errors:
      properties:
        errors:
          items:
            $ref: '#/components/schemas/numbers_Error'
          type: array
      type: object
    UpdateSubNumberOrderRequest:
      properties:
        regulatory_requirements:
          items:
            $ref: '#/components/schemas/UpdateRegulatoryRequirement'
          type: array
      type: object
    SubNumberOrder:
      properties:
        country_code:
          example: US
          readOnly: true
          type: string
        created_at:
          description: An ISO 8901 datetime string denoting when the number order was created.
          example: '2018-01-01T00:00:00.000000Z'
          format: date-time
          readOnly: true
          type: string
        customer_reference:
          description: A customer reference string for customer look ups.
          example: MY REF 001
          type: string
        id:
          example: 12ade33a-21c0-473b-b055-b3c836e1c292
          format: uuid
          readOnly: true
          type: string
        is_block_sub_number_order:
          description: True if the sub number order is a block sub number order
          example: false
          readOnly: true
          type: boolean
        order_request_id:
          example: 12ade33a-21c0-473b-b055-b3c836e1c293
          format: uuid
          readOnly: true
          type: string
        phone_number_type:
          enum:
          - local
          - toll_free
          - mobile
          - national
          - shared_cost
          - landline
          example: local
          type: string
        phone_numbers_count:
          description: The count of phone numbers in the number order.
          example: 1
          readOnly: true
          type: integer
        record_type:
          example: sub_number_order
          readOnly: true
          type: string
        regulatory_requirements:
          items:
            $ref: '#/components/schemas/SubNumberOrderRegulatoryRequirement'
          type: array
        requirements_met:
          description: True if all requirements are met for every phone number, false otherwise.
          example: true
          readOnly: true
          type: boolean
        status:
          description: The status of the order.
          enum:
          - pending
          - success
          - failure
          readOnly: true
          type: string
        updated_at:
          description: An ISO 8901 datetime string for when the number order was updated.
          example: '2018-01-01T00:00:00.000000Z'
          format: date-time
          readOnly: true
          type: string
        user_id:
          example: d70873cd-7c98-401a-81b6-b1ae08246995
          format: uuid
          type: string
      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
    SubNumberOrdersReport:
      example:
        created_at: '2025-06-11T13:21:40.967339+00:00'
        filters:
          country_code: US
          created_at_gt: '2023-04-05T10:22:08.230549Z'
          created_at_lt: '2025-06-05T10:22:08.230549Z'
          customer_reference: STRING
          order_request_id: 991b8ff5-4daf-4826-9a22-e3991b444a9c
          status: success
        id: cada7e84-122b-4b47-bc66-58c7c3becd40
        order_type: sub_number_order
        status: pending
        updated_at: '2025-06-11T13:21:45.753260+00:00'
        user_id: 0d7ef697-df19-413a-b724-56b0539f5397
      properties:
        created_at:
          description: ISO 8601 formatted date indicating when the resource was created.
          example: '2025-06-11T13:21:40.967339+00:00'
          format: date-time
          readOnly: true
          type: string
        filters:
          description: The filters that were applied to generate this report
          properties:
            country_code:
              example: US
              type: string
            created_at_gt:
              example: '2023-04-05T10:22:08.230549Z'
              format: date-time
              type: string
            created_at_lt:
              example: '2025-06-05T10:22:08.230549Z'
              format: date-time
              type: string
            customer_reference:
              example: STRING
              type: string
            order_request_id:
              example: 991b8ff5-4daf-4826-9a22-e3991b444a9c
              format: uuid
              type: string
            status:
              example: success
              type: string
          type: object
        id:
          description: Identifies the resource.
          example: cada7e84-122b-4b47-bc66-58c7c3becd40
          format: uuid
          readOnly: true
          type: string
        order_type:
          description: The type of order report.
          example: sub_number_order
          readOnly: true
          type: string
        status:
          default: pending
          description: Indicates the completion level of the sub number orders report. The report must have a status of 'success' before it can be downloaded.
          enum:
          - pending
          - success
          - failed
          - expired
          example: pending
          type: string
        updated_at:
          description: ISO 8601 formatted date indicating when the resource was updated.
          example: '2025-06-11T13:21:45.753260+00:00'
          format: date-time
          readOnly: true
          type: string
        user_id:
          description: The ID of the user who created the report.
          example: 0d7ef697-df19-413a-b724-56b0539f5397
          format: uuid
          readOnly: true
          type: string
      type: object
    PhoneNumbersJobPhoneNumber:
      properties:
        id:
          description: The phone number's ID
          type: string
        phone_number:
          description: The phone number in e164 format.
          example: '+19705555000'
          type: string
      type: object
    SubNumberOrderRegulatoryRequirementWithValue:
      properties:
        field_type:
          enum:
          - textual
          - datetime
          - address
          - document
          example: address
          readOnly: true
          type: string
        field_value:
          description: The value of the requirement, this could be an id to a resource or a string value.
          example: 45f45a04-b4be-4592-95b1-9306b9db2b21
          type: string
        record_type:
          example: phone_number_regulatory_requirement
          readOnly: true
          type: string
        requirement_id:
          description: Unique id for a requirement.
          example: 8ffb3622-7c6b-4ccc-b65f-7a3dc0099576
          format: uuid
          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