openapi: 3.1.0
info:
  contact:
    email: support@telnyx.com
  description: Telnyx provides global communications and connectivity APIs for developers — including SIP trunking, programmable voice, SMS, MMS, WhatsApp Business Messaging, Call Control, Fax, Wireless (IoT & eSIM), Phone Numbers (DID provisioning & porting), Emergency Services, and Network APIs for private interconnects and edge connectivity. Build, scale, and manage voice, messaging, and data networks with Telnyx's carrier-grade global infrastructure and API-first platform.
  title: Telnyx Access Tokens Requirement Groups API
  version: 2.0.0
  x-endpoint-cost: light
servers:
- description: Version 2.0.0 of the Telnyx API
  url: https://api.telnyx.com/v2
security:
- bearerAuth: []
tags:
- description: Requirement Groups
  name: Requirement Groups
paths:
  /number_order_phone_numbers/{id}/requirement_group:
    post:
      operationId: updateNumberOrderPhoneNumberRequirementGroup
      parameters:
      - description: The unique identifier of the number order phone number
        in: path
        name: id
        required: true
        schema:
          format: uuid
          type: string
      requestBody:
        content:
          application/json:
            schema:
              properties:
                requirement_group_id:
                  description: The ID of the requirement group to associate
                  format: uuid
                  type: string
              required:
              - requirement_group_id
              type: object
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/NumberOrderPhoneNumberRequirementGroupResponse'
                type: object
          description: Successful response with updated phone number order details
        '400':
          $ref: '#/components/responses/numbers_BadRequestResponse'
        '401':
          $ref: '#/components/responses/numbers_UnauthorizedResponse'
        '404':
          $ref: '#/components/responses/numbers_NotFoundResponse'
        '422':
          $ref: '#/components/responses/numbers_UnprocessableEntity'
        '500':
          $ref: '#/components/responses/numbers_GenericErrorResponse'
      summary: Update requirement group for a phone number order
      tags:
      - Requirement Groups
      x-latency-category: responsive
  /requirement_groups:
    get:
      operationId: GetRequirementGroups
      parameters:
      - description: 'Consolidated filter parameter (deepObject style). Originally: filter[country_code], filter[phone_number_type], filter[action], filter[status], filter[customer_reference]'
        explode: true
        in: query
        name: filter
        schema:
          properties:
            action:
              description: Filter requirement groups by action type
              enum:
              - ordering
              - porting
              - action
              type: string
            country_code:
              description: Filter requirement groups by country code (iso alpha 2)
              type: string
            customer_reference:
              description: Filter requirement groups by customer reference
              type: string
            phone_number_type:
              description: Filter requirement groups by phone number type.
              enum:
              - local
              - toll_free
              - mobile
              - national
              - shared_cost
              type: string
            status:
              description: Filter requirement groups by status
              enum:
              - approved
              - unapproved
              - pending-approval
              - declined
              - expired
              type: string
          type: object
        style: deepObject
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/RequirementGroup'
                type: array
          description: List requirement groups
        '400':
          $ref: '#/components/responses/numbers_BadRequestResponse'
        '401':
          $ref: '#/components/responses/numbers_UnauthorizedResponse'
        '422':
          $ref: '#/components/responses/numbers_UnprocessableEntity'
        '500':
          $ref: '#/components/responses/numbers_GenericErrorResponse'
      summary: List requirement groups
      tags:
      - Requirement Groups
      x-latency-category: responsive
    post:
      operationId: CreateRequirementGroup
      requestBody:
        content:
          application/json:
            schema:
              properties:
                action:
                  enum:
                  - ordering
                  - porting
                  example: ordering
                  type: string
                country_code:
                  description: ISO alpha 2 country code
                  example: US
                  type: string
                customer_reference:
                  example: My Requirement Group
                  type: string
                phone_number_type:
                  enum:
                  - local
                  - toll_free
                  - mobile
                  - national
                  - shared_cost
                  example: local
                  type: string
                regulatory_requirements:
                  items:
                    properties:
                      field_value:
                        type: string
                      requirement_id:
                        type: string
                    type: object
                  type: array
              required:
              - country_code
              - phone_number_type
              - action
              type: object
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequirementGroup'
          description: Requirement group created
        '400':
          $ref: '#/components/responses/numbers_BadRequestResponse'
        '401':
          $ref: '#/components/responses/numbers_UnauthorizedResponse'
        '422':
          $ref: '#/components/responses/numbers_UnprocessableEntity'
        '500':
          $ref: '#/components/responses/numbers_GenericErrorResponse'
      summary: Create a new requirement group
      tags:
      - Requirement Groups
      x-latency-category: responsive
  /requirement_groups/{id}:
    delete:
      operationId: DeleteRequirementGroup
      parameters:
      - description: ID of the requirement group
        in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequirementGroup'
          description: Deleted requirement group
        '400':
          $ref: '#/components/responses/numbers_BadRequestResponse'
        '401':
          $ref: '#/components/responses/numbers_UnauthorizedResponse'
        '404':
          $ref: '#/components/responses/numbers_NotFoundResponse'
        '422':
          $ref: '#/components/responses/numbers_UnprocessableEntity'
        '500':
          $ref: '#/components/responses/numbers_GenericErrorResponse'
      summary: Delete a requirement group by ID
      tags:
      - Requirement Groups
      x-latency-category: responsive
    get:
      operationId: GetRequirementGroup
      parameters:
      - description: ID of the requirement group to retrieve
        in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequirementGroup'
          description: A single requirement group
        '400':
          $ref: '#/components/responses/numbers_BadRequestResponse'
        '401':
          $ref: '#/components/responses/numbers_UnauthorizedResponse'
        '404':
          $ref: '#/components/responses/numbers_NotFoundResponse'
        '422':
          $ref: '#/components/responses/numbers_UnprocessableEntity'
        '500':
          $ref: '#/components/responses/numbers_GenericErrorResponse'
      summary: Get a single requirement group by ID
      tags:
      - Requirement Groups
      x-latency-category: responsive
    patch:
      operationId: UpdateRequirementGroup
      parameters:
      - description: ID of the requirement group
        in: path
        name: id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              properties:
                customer_reference:
                  description: Reference for the customer
                  example: '0002'
                  type: string
                regulatory_requirements:
                  items:
                    properties:
                      field_value:
                        description: New value for the regulatory requirement
                        example: new requirement value
                        type: string
                      requirement_id:
                        description: Unique identifier for the regulatory requirement
                        example: 53970723-fbff-4f46-a975-f62be6c1a585
                        type: string
                    type: object
                  type: array
              type: object
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequirementGroup'
          description: Updated requirement group
        '400':
          $ref: '#/components/responses/numbers_BadRequestResponse'
        '401':
          $ref: '#/components/responses/numbers_UnauthorizedResponse'
        '404':
          $ref: '#/components/responses/numbers_NotFoundResponse'
        '422':
          $ref: '#/components/responses/numbers_UnprocessableEntity'
        '500':
          $ref: '#/components/responses/numbers_GenericErrorResponse'
      summary: Update requirement values in requirement group
      tags:
      - Requirement Groups
      x-latency-category: responsive
  /requirement_groups/{id}/submit_for_approval:
    post:
      operationId: SubmitRequirementGroup
      parameters:
      - description: ID of the requirement group to submit
        in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequirementGroup'
          description: A single requirement group
        '400':
          $ref: '#/components/responses/numbers_BadRequestResponse'
        '401':
          $ref: '#/components/responses/numbers_UnauthorizedResponse'
        '404':
          $ref: '#/components/responses/numbers_NotFoundResponse'
        '422':
          $ref: '#/components/responses/numbers_UnprocessableEntity'
        '500':
          $ref: '#/components/responses/numbers_GenericErrorResponse'
      summary: Submit a Requirement Group for Approval
      tags:
      - Requirement Groups
      x-latency-category: responsive
  /sub_number_orders/{id}/requirement_group:
    post:
      operationId: updateSubNumberOrderRequirementGroup
      parameters:
      - description: The ID of the sub number order
        in: path
        name: id
        required: true
        schema:
          format: uuid
          type: string
      requestBody:
        content:
          application/json:
            example:
              requirement_group_id: a4b201f9-8646-4e54-a7d2-b2e403eeaf8c
            schema:
              properties:
                requirement_group_id:
                  description: The ID of the requirement group to associate
                  format: uuid
                  type: string
              required:
              - requirement_group_id
              type: object
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubNumberOrderRequirementGroupResponse'
          description: Sub number order requirement group updated successfully
        '400':
          $ref: '#/components/responses/numbers_BadRequestResponse'
        '401':
          $ref: '#/components/responses/numbers_UnauthorizedResponse'
        '404':
          $ref: '#/components/responses/numbers_NotFoundResponse'
        '422':
          $ref: '#/components/responses/numbers_UnprocessableEntity'
        '500':
          $ref: '#/components/responses/numbers_GenericErrorResponse'
      summary: Update requirement group for a sub number order
      tags:
      - Requirement Groups
      x-latency-category: responsive
components:
  schemas:
    RequirementGroup:
      properties:
        action:
          type: string
        country_code:
          type: string
        created_at:
          format: date-time
          type: string
        customer_reference:
          type: string
        id:
          type: string
        phone_number_type:
          type: string
        record_type:
          example: requirement_group
          type: string
        regulatory_requirements:
          items:
            $ref: '#/components/schemas/UserRequirement'
          type: array
        status:
          enum:
          - approved
          - unapproved
          - pending-approval
          - declined
          - expired
          type: string
        updated_at:
          format: date-time
          type: string
      type: object
    UserRequirement:
      properties:
        created_at:
          format: date-time
          type: string
        expires_at:
          format: date-time
          type: string
        field_type:
          type: string
        field_value:
          type: string
        requirement_id:
          type: string
        status:
          enum:
          - approved
          - unapproved
          - pending-approval
          - declined
          - expired
          type: string
        updated_at:
          format: date-time
          type: string
      type: object
    NumberOrderPhoneNumberRequirementGroupResponse:
      properties:
        bundle_id:
          format: uuid
          type:
          - string
          - 'null'
        country_code:
          example: AT
          type: string
        deadline:
          format: date-time
          type: string
        id:
          example: 613d517a-0432-4bae-a785-c11033bd0985
          format: uuid
          type: string
        is_block_number:
          example: false
          type: boolean
        locality:
          example: AUSTRIA
          type: string
        order_request_id:
          example: a11d58fe-88a4-494a-b752-8dea411993c6
          format: uuid
          type: string
        phone_number:
          example: '+43800300238'
          type: string
        phone_number_type:
          example: toll_free
          type: string
        record_type:
          example: number_order_phone_number
          type: string
        regulatory_requirements:
          items:
            properties:
              field_type:
                example: textual
                type: string
              field_value:
                example: '1234567890'
                type: string
              requirement_id:
                format: uuid
                type: string
              status:
                example: pending-approval
                type: string
            type: object
          type: array
        requirements_met:
          example: false
          type: boolean
        requirements_status:
          example: requirement-info-under-review
          type: string
        status:
          example: pending
          type: string
        sub_number_order_id:
          example: f826ed66-b27c-4340-9dc0-57dc3459f1bd
          format: uuid
          type: string
      type: object
    SubNumberOrderRequirementGroupResponse:
      example:
        data:
          country_code: AT
          created_at: '2018-01-01T00:00:00.000000Z'
          customer_reference: missing
          id: f826ed66-b27c-4340-9dc0-57dc3459f1bd
          is_block_sub_number_order: false
          order_request_id: a11d58fe-88a4-494a-b752-8dea411993c6
          phone_number_type: toll_free
          phone_numbers:
          - bundle_id: a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d
            country_code: AT
            id: 613d517a-0432-4bae-a785-c11033bd0985
            phone_number: '+43800300238'
            phone_number_type: toll_free
            record_type: number_order_phone_number
            regulatory_requirements:
            - field_type: textual
              field_value: '4804570924'
              requirement_id: 2708e569-696a-4fc7-9305-5fdb3eb9c7dd
              status: pending-approval
            requirements_met: false
            requirements_status: requirement-info-under-review
            status: pending
          phone_numbers_count: 1
          record_type: sub_number_order
          regulatory_requirements:
          - field_type: textual
            record_type: phone_number_regulatory_requirement
            requirement_id: 2708e569-696a-4fc7-9305-5fdb3eb9c7dd
          requirements_met: false
          status: pending
          updated_at: '2018-01-01T00:00:00.000000Z'
      properties:
        data:
          properties:
            country_code:
              type: string
            created_at:
              format: date-time
              type: string
            customer_reference:
              type: string
            id:
              format: uuid
              type: string
            is_block_sub_number_order:
              type: boolean
            order_request_id:
              format: uuid
              type: string
            phone_number_type:
              type: string
            phone_numbers:
              items:
                $ref: '#/components/schemas/SubNumberOrderPhoneNumber'
              type: array
            phone_numbers_count:
              type: integer
            record_type:
              type: string
            regulatory_requirements:
              items:
                $ref: '#/components/schemas/RegulatoryRequirement'
              type: array
            requirements_met:
              type: boolean
            status:
              type: string
            updated_at:
              format: date-time
              type: string
          type: object
      type: object
    RegulatoryRequirement:
      properties:
        field_type:
          type: string
        record_type:
          type: string
        requirement_id:
          format: uuid
          type: string
      type: object
    numbers_Errors:
      properties:
        errors:
          items:
            $ref: '#/components/schemas/numbers_Error'
          type: array
      type: object
    numbers_Error:
      properties:
        code:
          example: '10007'
          type: string
        detail:
          example: An unexpected error occured.
          type: string
        meta:
          properties:
            url:
              description: URL with additional information on the error.
              example: https://developers.telnyx.com/docs/overview/errors/10015
              type: string
          type: object
        source:
          properties:
            parameter:
              description: Indicates which query parameter caused the error.
              type: string
            pointer:
              description: JSON pointer (RFC6901) to the offending entity.
              example: /base
              type: string
          type: object
        title:
          example: Unexpected error
          type: string
      type: object
    SubNumberOrderPhoneNumber:
      properties:
        bundle_id:
          format: uuid
          type:
          - string
          - 'null'
        country_code:
          type: string
        id:
          format: uuid
          type: string
        phone_number:
          type: string
        phone_number_type:
          type: string
        record_type:
          type: string
        regulatory_requirements:
          items:
            properties:
              field_type:
                type: string
              field_value:
                type: string
              requirement_id:
                format: uuid
                type: string
              status:
                type: string
            type: object
          type: array
        requirements_met:
          type: boolean
        requirements_status:
          type: string
        status:
          type: string
      type: object
  responses:
    numbers_UnauthorizedResponse:
      content:
        application/json:
          examples:
            Authentication Failed:
              value:
                errors:
                - code: '10009'
                  detail: Could not understand the provided credentials.
                  meta:
                    url: https://developers.telnyx.com/docs/overview/errors/10009
                  title: Authentication failed
          schema:
            $ref: '#/components/schemas/numbers_Errors'
      description: Unauthorized
    numbers_UnprocessableEntity:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/numbers_Errors'
      description: Unprocessable entity. Check the 'detail' field in response for details.
    numbers_NotFoundResponse:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/numbers_Errors'
      description: The requested resource doesn't exist.
    numbers_GenericErrorResponse:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/numbers_Errors'
      description: Unexpected error
    numbers_BadRequestResponse:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/numbers_Errors'
      description: Bad request, the request was unacceptable, often due to missing a required parameter.
  securitySchemes:
    bearerAuth:
      scheme: bearer
      type: http
    branded-calling_bearerAuth:
      description: API key passed as a Bearer token in the Authorization header
      scheme: bearer
      type: http
    oauthClientAuth:
      description: OAuth 2.0 authentication for Telnyx API and MCP integrations
      flows:
        authorizationCode:
          authorizationUrl: https://api.telnyx.com/v2/oauth/authorize
          refreshUrl: https://api.telnyx.com/v2/oauth/token
          scopes:
            admin: Administrative access to Telnyx resources
          tokenUrl: https://api.telnyx.com/v2/oauth/token
        clientCredentials:
          scopes:
            admin: Administrative access to Telnyx resources
          tokenUrl: https://api.telnyx.com/v2/oauth/token
      type: oauth2
    outbound-voice-profiles_bearerAuth:
      bearerFormat: JWT
      scheme: bearer
      type: http
    pronunciation-dicts_bearerAuth:
      description: Telnyx API v2 key. Obtain from https://portal.telnyx.com
      scheme: bearer
      type: http
    stored-payment-transactions_bearerAuth:
      bearerFormat: JWT
      scheme: bearer
      type: http