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 Verify 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: Two factor authentication API
  name: Verify
paths:
  /verifications/by_phone_number/{phone_number}:
    get:
      operationId: ListVerifications
      parameters:
      - description: The phone number associated with the verifications to retrieve.
        in: path
        name: phone_number
        required: true
        schema:
          description: +E164 formatted phone number.
          example: '+13035551234'
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListVerificationsResponse'
          description: Expected verifications response to a valid request.
        '400':
          $ref: '#/components/responses/verify_GenericErrorResponse'
      summary: List verifications by phone number
      tags:
      - Verify
      x-latency-category: responsive
  /verifications/by_phone_number/{phone_number}/actions/verify:
    post:
      operationId: VerifyVerificationCodeByPhoneNumber
      parameters:
      - description: The phone number associated with the verification code being verified.
        in: path
        name: phone_number
        required: true
        schema:
          description: +E164 formatted phone number.
          example: '+13035551234'
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VerifyVerificationCodeRequestByPhoneNumber'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerifyVerificationCodeResponse'
          description: Expected verify response to a valid request.
        '400':
          $ref: '#/components/responses/verify_GenericErrorResponse'
      summary: Verify verification code by phone number
      tags:
      - Verify
      x-latency-category: responsive
  /verifications/call:
    post:
      operationId: CreateVerificationCall
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateVerificationRequestCall'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateVerificationResponse'
          description: Expected verifications response to a valid request.
        '400':
          $ref: '#/components/responses/verify_GenericErrorResponse'
      summary: Trigger Call verification
      tags:
      - Verify
      x-latency-category: responsive
  /verifications/flashcall:
    post:
      operationId: CreateFlashcallVerification
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateVerificationRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateVerificationResponse'
          description: Expected verifications response to a valid request.
        '400':
          $ref: '#/components/responses/verify_GenericErrorResponse'
      summary: Trigger Flash call verification
      tags:
      - Verify
      x-latency-category: responsive
  /verifications/sms:
    post:
      operationId: CreateVerificationSms
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateVerificationRequestSMS'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateVerificationResponse'
          description: Expected verifications response to a valid request.
        '400':
          $ref: '#/components/responses/verify_GenericErrorResponse'
      summary: Trigger SMS verification
      tags:
      - Verify
      x-latency-category: responsive
  /verifications/whatsapp:
    post:
      operationId: CreateWhatsappVerification
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateVerificationRequestSMS'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateVerificationResponse'
          description: Expected verifications response to a valid request.
        '400':
          $ref: '#/components/responses/verify_GenericErrorResponse'
      summary: Trigger WhatsApp verification
      tags:
      - Verify
      x-latency-category: responsive
  /verifications/{verification_id}:
    get:
      operationId: RetrieveVerification
      parameters:
      - description: The identifier of the verification to retrieve.
        in: path
        name: verification_id
        required: true
        schema:
          example: 12ade33a-21c0-473b-b055-b3c836e1c292
          format: uuid
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RetrieveVerificationResponse'
          description: Expected verifications response to a valid request.
        '400':
          $ref: '#/components/responses/verify_GenericErrorResponse'
      summary: Retrieve verification
      tags:
      - Verify
      x-latency-category: responsive
  /verifications/{verification_id}/actions/verify:
    post:
      operationId: VerifyVerificationCodeById
      parameters:
      - description: The identifier of the verification to retrieve.
        in: path
        name: verification_id
        required: true
        schema:
          example: 12ade33a-21c0-473b-b055-b3c836e1c292
          format: uuid
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VerifyVerificationCodeRequestById'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerifyVerificationCodeResponse'
          description: Expected verify response to a valid request.
        '400':
          $ref: '#/components/responses/verify_GenericErrorResponse'
      summary: Verify verification code by ID
      tags:
      - Verify
      x-latency-category: responsive
  /verify_profiles:
    get:
      description: Gets a paginated list of Verify profiles.
      operationId: ListProfiles
      parameters:
      - description: 'Consolidated filter parameter (deepObject style). Originally: filter[name]'
        explode: true
        in: query
        name: filter
        required: false
        schema:
          properties:
            name:
              description: Optional filter for profile names.
              title: filter[name]
              type: string
          type: object
        style: deepObject
      - description: 'Consolidated page parameter (deepObject style). Originally: page[size], page[number]'
        explode: true
        in: query
        name: page
        required: false
        schema:
          properties:
            number:
              default: 1
              title: page[number]
              type: integer
            size:
              default: 25
              title: page[size]
              type: integer
          type: object
        style: deepObject
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListVerifyProfilesResponse'
          description: Expected Verify profile response to a valid request.
        '400':
          $ref: '#/components/responses/verify_GenericErrorResponse'
      summary: List all Verify profiles
      tags:
      - Verify
      x-group-parameters: 'true'
      x-latency-category: responsive
    post:
      description: Creates a new Verify profile to associate verifications with.
      operationId: CreateVerifyProfile
      requestBody:
        content:
          application/json:
            schema:
              properties:
                call:
                  $ref: '#/components/schemas/CreateVerifyProfileCallRequest'
                  additionalProperties: true
                  type: object
                daily_spend_limit:
                  description: The maximum daily spend allowed on this verify profile, in USD.
                  example: 100.0
                  minimum: 0
                  type: number
                daily_spend_limit_enabled:
                  default: false
                  description: Whether the daily spend limit is enforced for this verify profile.
                  example: true
                  type: boolean
                flashcall:
                  $ref: '#/components/schemas/CreateVerifyProfileSettingsRequest'
                  additionalProperties: true
                  type: object
                language:
                  example: en-US
                  type: string
                name:
                  example: Test Profile
                  type: string
                sms:
                  $ref: '#/components/schemas/CreateVerifyProfileSMSRequest'
                  additionalProperties: true
                  type: object
                webhook_failover_url:
                  example: http://example.com/webhook/failover
                  type: string
                webhook_url:
                  example: http://example.com/webhook
                  type: string
                whatsapp:
                  $ref: '#/components/schemas/CreateVerifyProfileSettingsWhatsAppRequest'
                  additionalProperties: true
                  type: object
              required:
              - name
              title: Create Verify Profile Request
              type: object
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerifyProfileResponseDataWrapper'
          description: Expected Verify profile response to a valid request.
        '400':
          $ref: '#/components/responses/verify_GenericErrorResponse'
      summary: Create a Verify profile
      tags:
      - Verify
      x-latency-category: responsive
  /verify_profiles/templates:
    get:
      description: List all Verify profile message templates.
      operationId: ListProfileMessageTemplates
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListVerifyProfileMessageTemplateResponse'
          description: Expected Verify profile message template response to a valid request.
        '400':
          $ref: '#/components/responses/verify_GenericErrorResponse'
        '500':
          $ref: '#/components/responses/verify_GenericErrorResponse'
      summary: Retrieve Verify profile message templates
      tags:
      - Verify
      x-latency-category: responsive
    post:
      description: Create a new Verify profile message template.
      operationId: CreateMessageTemplate
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateMessageTemplateRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageTemplateResponseDataWrapper'
          description: Expected message template response to a valid request.
        '400':
          $ref: '#/components/responses/verify_GenericErrorResponse'
      summary: Create message template
      tags:
      - Verify
      x-latency-category: responsive
  /verify_profiles/templates/{template_id}:
    patch:
      description: Update an existing Verify profile message template.
      operationId: UpdateMessageTemplate
      parameters:
      - description: The identifier of the message template to update.
        in: path
        name: template_id
        required: true
        schema:
          example: 12ade33a-21c0-473b-b055-b3c836e1c292
          format: uuid
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateMessageTemplateRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageTemplateResponseDataWrapper'
          description: Expected message template response to a valid request.
        '400':
          $ref: '#/components/responses/verify_GenericErrorResponse'
      summary: Update message template
      tags:
      - Verify
      x-latency-category: responsive
  /verify_profiles/{verify_profile_id}:
    delete:
      operationId: DeleteProfile
      parameters:
      - description: The identifier of the Verify profile to delete.
        in: path
        name: verify_profile_id
        required: true
        schema:
          example: 12ade33a-21c0-473b-b055-b3c836e1c292
          format: uuid
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerifyProfileResponseDataWrapper'
          description: Expected Verify profile response to a valid request.
        '400':
          $ref: '#/components/responses/verify_GenericErrorResponse'
      summary: Delete Verify profile
      tags:
      - Verify
      x-latency-category: responsive
    get:
      description: Gets a single Verify profile.
      operationId: GetVerifyProfile
      parameters:
      - description: The identifier of the Verify profile to retrieve.
        in: path
        name: verify_profile_id
        required: true
        schema:
          example: 12ade33a-21c0-473b-b055-b3c836e1c292
          format: uuid
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerifyProfileResponseDataWrapper'
          description: Expected Verify profile response to a valid request.
        '400':
          $ref: '#/components/responses/verify_GenericErrorResponse'
      summary: Retrieve Verify profile
      tags:
      - Verify
      x-latency-category: responsive
    patch:
      operationId: UpdateVerifyProfile
      parameters:
      - description: The identifier of the Verify profile to update.
        in: path
        name: verify_profile_id
        required: true
        schema:
          example: 12ade33a-21c0-473b-b055-b3c836e1c292
          format: uuid
          type: string
      requestBody:
        content:
          application/json:
            schema:
              properties:
                call:
                  $ref: '#/components/schemas/UpdateVerifyProfileCallRequest'
                  additionalProperties: true
                  type: object
                daily_spend_limit:
                  description: The maximum daily spend allowed on this verify profile, in USD.
                  example: 100.0
                  minimum: 0
                  type: number
                daily_spend_limit_enabled:
                  description: Whether the daily spend limit is enforced for this verify profile.
                  example: true
                  type: boolean
                language:
                  example: en-US
                  type: string
                name:
                  example: Test Profile
                  type: string
                sms:
                  $ref: '#/components/schemas/UpdateVerifyProfileSMSRequest'
                  additionalProperties: true
                  type: object
                webhook_failover_url:
                  example: http://example.com/webhook/failover
                  type: string
                webhook_url:
                  example: http://example.com/webhook
                  type: string
                whatsapp:
                  $ref: '#/components/schemas/UpdateVerifyProfileSettingsWhatsAppRequest'
                  additionalProperties: true
                  type: object
              title: Update Verify Profile Request
              type: object
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerifyProfileResponseDataWrapper'
          description: Expected Verify profile response to a valid request.
        '400':
          $ref: '#/components/responses/verify_GenericErrorResponse'
      summary: Update Verify profile
      tags:
      - Verify
      x-latency-category: responsive
components:
  schemas:
    ListVerificationsResponse:
      properties:
        data:
          items:
            $ref: '#/components/schemas/Verification'
          type: array
        meta:
          $ref: '#/components/schemas/verify_Meta'
      required:
      - data
      - meta
      title: ListVerificationsResponse
      type: object
    VerifyProfileFlashcallResponse:
      properties:
        app_name:
          description: The name that identifies the application requesting 2fa in the verification message.
          example: Example Secure App
          pattern: ^[A-Za-z0-9 -]{1,30}$
          type: string
        default_verification_timeout_secs:
          default: 300
          description: For every request that is initiated via this Verify profile, this sets the number of seconds before a verification request code expires. Once the verification request expires, the user cannot use the code to verify their identity.
          example: 300
          type: integer
      title: VerifyProfileFlashcallResponse
      type: object
    CreateVerifyProfileSettingsWhatsAppRequest:
      properties:
        default_verification_timeout_secs:
          default: 300
          description: For every request that is initiated via this Verify profile, this sets the number of seconds before a verification request code expires. Once the verification request expires, the user cannot use the code to verify their identity.
          example: 300
          type: integer
        sender_phone_number:
          default: null
          description: Phone number registered on the customer WABA to send OTPs from
          example: '+13035551234'
          type:
          - string
          - 'null'
        template_id:
          default: null
          description: Customer pre-approved authentication template name registered on Meta
          example: authentication_template_name
          type:
          - string
          - 'null'
        waba_id:
          default: null
          description: Customer Meta WABA ID for Bring-Your-Own-WABA sending
          example: '1234567890'
          type:
          - string
          - 'null'
        whitelisted_destinations:
          description: Enabled country destinations to send verification codes. The elements in the list must be valid ISO 3166-1 alpha-2 country codes. If set to `["*"]`, all destinations will be allowed. **Conditionally required:** this field must be provided when your organization is configured to require explicit whitelisted destinations; otherwise it is optional.
          example:
          - US
          - CA
          items:
            description: ISO 3166-1 alpha-2 country code
            pattern: ^[A-Z]{2}$
            type: string
          type: array
      title: CreateVerifyProfileSettingsWhatsAppRequest
      type: object
    RetrieveVerificationResponse:
      properties:
        data:
          $ref: '#/components/schemas/Verification'
      required:
      - data
      title: RetrieveVerificationResponse
      type: object
    VerifyProfileWhatsAppResponse:
      properties:
        app_name:
          description: The name that identifies the application requesting 2fa in the verification message.
          example: Example Secure App
          pattern: ^[A-Za-z0-9 -]{1,30}$
          type: string
        code_length:
          default: 5
          description: The length of the verify code to generate.
          example: 6
          type: integer
        default_verification_timeout_secs:
          default: 300
          description: For every request that is initiated via this Verify profile, this sets the number of seconds before a verification request code expires. Once the verification request expires, the user cannot use the code to verify their identity.
          example: 300
          type: integer
        messaging_template_id:
          description: The message template identifier selected from /verify_profiles/templates
          example: 0abb5b4f-459f-445a-bfcd-488998b7572d
          format: uuid
          type: string
        sender_phone_number:
          default: null
          description: Phone number registered on the customer WABA to send OTPs from
          example: '+13035551234'
          type:
          - string
          - 'null'
        template_id:
          default: null
          description: Customer pre-approved authentication template name registered on Meta
          example: authentication_template_name
          type:
          - string
          - 'null'
        waba_id:
          default: null
          description: Customer Meta WABA ID for Bring-Your-Own-WABA sending
          example: '1234567890'
          type:
          - string
          - 'null'
        whitelisted_destinations:
          description: Enabled country destinations to send verification codes. The elements in the list must be valid ISO 3166-1 alpha-2 country codes. If set to `["*"]`, all destinations will be allowed. **Conditionally required:** this field must be provided when your organization is configured to require explicit whitelisted destinations; otherwise it is optional.
          example:
          - US
          - CA
          items:
            description: ISO 3166-1 alpha-2 country code
            pattern: ^[A-Z]{2}$
            type: string
          type: array
      title: VerifyProfileWhatsAppResponse
      type: object
    UpdateVerifyProfileSettingsWhatsAppRequest:
      properties:
        default_verification_timeout_secs:
          default: 300
          description: For every request that is initiated via this Verify profile, this sets the number of seconds before a verification request code expires. Once the verification request expires, the user cannot use the code to verify their identity.
          example: 300
          type: integer
        sender_phone_number:
          default: null
          description: Phone number registered on the customer WABA to send OTPs from
          example: '+13035551234'
          type:
          - string
          - 'null'
        template_id:
          default: null
          description: Customer pre-approved authentication template name registered on Meta
          example: authentication_template_name
          type:
          - string
          - 'null'
        waba_id:
          default: null
          description: Customer Meta WABA ID for Bring-Your-Own-WABA sending
          example: '1234567890'
          type:
          - string
          - 'null'
        whitelisted_destinations:
          description: Enabled country destinations to send verification codes. The elements in the list must be valid ISO 3166-1 alpha-2 country codes. If set to `["*"]`, all destinations will be allowed. **Conditionally required:** this field must be provided when your organization is configured to require explicit whitelisted destinations; otherwise it is optional.
          example:
          - US
          - CA
          items:
            description: ISO 3166-1 alpha-2 country code
            pattern: ^[A-Z]{2}$
            type: string
          type: array
      title: UpdateVerifyProfileSettingsWhatsAppRequest
      type: object
    VerificationStatus:
      description: The possible statuses of the verification request.
      enum:
      - pending
      - accepted
      - invalid
      - expired
      - error
      example: accepted
      title: VerificationStatus
      type: string
    CreateVerifyProfileSMSRequest:
      properties:
        alpha_sender:
          default: Telnyx
          description: The alphanumeric sender ID to use when sending to destinations that require an alphanumeric sender ID.
          pattern: ^[A-Za-z0-9 ]{1,11}$
          type:
          - string
          - 'null'
        app_name:
          description: The name that identifies the application requesting 2fa in the verification message.
          example: Example Secure App
          pattern: ^[A-Za-z0-9 -]{1,30}$
          type: string
        code_length:
          default: 5
          description: The length of the verify code to generate.
          example: 6
          type: integer
        default_verification_timeout_secs:
          default: 300
          description: For every request that is initiated via this Verify profile, this sets the number of seconds before a verification request code expires. Once the verification request expires, the user cannot use the code to verify their identity.
          example: 300
          type: integer
        messaging_template_id:
          description: The message template identifier selected from /verify_profiles/templates
          example: 0abb5b4f-459f-445a-bfcd-488998b7572d
          format: uuid
          type: string
        whitelisted_destinations:
          description: Enabled country destinations to send verification codes. The elements in the list must be valid ISO 3166-1 alpha-2 country codes. If set to `["*"]`, all destinations will be allowed. **Conditionally required:** this field must be provided when your organization is configured to require explicit whitelisted destinations; otherwise it is optional.
          example:
          - US
          - CA
          items:
            description: ISO 3166-1 alpha-2 country code
            pattern: ^[A-Z]{2}$
            type: string
          type: array
      title: CreateVerifyProfileSMSRequest
      type: object
    VerifyVerificationCodeRequestById:
      properties:
        code:
          description: This is the code the user submits for verification.
          example: '17686'
          type: string
        status:
          description: Identifies if the verification code has been accepted or rejected. Only permitted if custom_code was used for the verification.
          enum:
          - accepted
          - rejected
          example: accepted
          type: string
      title: VerifyVerificationCodeRequestById
      type: object
    CreateVerificationResponse:
      properties:
        data:
          $ref: '#/components/schemas/Verification'
      required:
      - data
      title: CreateVerifyVerificationResponse
      type: object
    CreateMessageTemplateRequest:
      description: The request body when creating a message template.
      properties:
        text:
          description: The text content of the message template.
          example: 'Your {{app_name}} verification code is: {{code}}.'
          type: string
      required:
      - text
      title: CreateMessageTemplateRequest
      type: object
    CreateVerificationRequestSMS:
      description: The request body when creating a verification.
      properties:
        custom_code:
          default: null
          description: Send a self-generated numeric code to the end-user
          example: '43612'
          type:
          - string
          - 'null'
        phone_number:
          description: +E164 formatted phone number.
          example: '+13035551234'
          type: string
        timeout_secs:
          description: The number of seconds the verification code is valid for.
          example: 300
          type: integer
        verify_profile_id:
          description: The identifier of the associated Verify profile.
          example: 12ade33a-21c0-473b-b055-b3c836e1c292
          format: uuid
          type: string
      required:
      - phone_number
      - verify_profile_id
      title: CreateVerificationRequestSMS
      type: object
    verify_Meta:
      properties:
        page_number:
          example: 2
          type: integer
        page_size:
          example: 25
          type: integer
        total_pages:
          example: 3
          type: integer
        total_results:
          example: 55
          type: integer
      required:
      - total_pages
      - total_results
      - page_size
      - page_number
      type: object
    VerifyProfileSMSResponse:
      properties:
        alpha_sender:
          default: Telnyx
          description: The alphanumeric sender ID to use when sending to destinations that require an alphanumeric sender ID.
          pattern: ^[A-Za-z0-9 ]{1,11}$
          type:
          - string
          - 'null'
        app_name:
          description: The name that identifies the application requesting 2fa in the verification message.
          example: Example Secure App
          pattern: ^[A-Za-z0-9 -]{1,30}$
          type: string
        code_length:
          default: 5
          description: The length of the verify code to generate.
          example: 6
          type: integer
        default_verification_timeout_secs:
          default: 300
          description: For every request that is initiated via this Verify profile, this sets the number of seconds before a verification request code expires. Once the verification request expires, the user cannot use the code to verify their identity.
          example: 300
          type: integer
        messaging_template_id:
          description: The message template identifier selected from /verify_profiles/templates
          example: 0abb5b4f-459f-445a-bfcd-488998b7572d
          format: uuid
          type: string
        whitelisted_destinations:
          description: Enabled country destinations to send verification codes. The elements in the list must be valid ISO 3166-1 alpha-2 country codes. If set to `["*"]`, all destinations will be allowed. **Conditionally required:** this field must be provided when your organization is configured to require explicit whitelisted destinations; otherwise it is optional.
          example:
          - US
          - CA
          items:
            description: ISO 3166-1 alpha-2 country code
            pattern: ^[A-Z]{2}$
            type: string
          type: array
      title: VerifyProfileSMSResponse
      type: object
    UpdateMessageTemplateRequest:
      description: The request body when updating a message template.
      properties:
        text:
          description: The text content of the message template.
          example: 'Your {{app_name}} verification code is: {{code}}.'
          type: string
      required:
      - text
      title: UpdateMessageTemplateRequest
      type: object
    CreateVerifyProfileSettingsRequest:
      properties:
        app_name:
          description: The name that identifies the application requesting 2fa in the verification message.
          example: Example Secure App
          pattern: ^[A-Za-z0-9 -]{1,30}$
          type: string
        default_verification_timeout_secs:
          default: 300
          description: For every request that is initiated via this Verify profile, this sets the number of seconds before a verification request code expires. Once the verification request expires, the user cannot use the code to verify their identity.
          example: 300
          type: integer
        whitelisted_destinations:
          description: Enabled country destinations to send verification codes. The elements in the list must be valid ISO 3166-1 alpha-2 country codes. If set to `["*"]`, all destinations will be allowed. **Conditionally required:** this field must be provided when your organization is configured to require explicit whitelisted destinations; otherwise it is optional.
          example:
          - US
          - CA
          items:
            description: ISO 3166-1 alpha-2 country code
            pattern: ^[A-Z]{2}$
            type: string
          type: array
      title: CreateVerifyProfileSettingsRequest
      type: object
    VerifyProfileResponse:
      properties:
        call:
          $ref: '#/components/schemas/VerifyProfileCallResponse'
          additionalProperties: true
          type: object
        created_at:
          example: '2020-09-14T17:03:32.965812'
          type: string
        daily_spend_limit:
          description: The maximum daily spend allowed on this verify profile, in USD.
          example: 100.0
          minimum: 0
          type: number
        daily_spend_limit_enabled:
          default: false
          description: Whether the daily spend limit is enforced for this verify profile.
          example: true
          type: boolean
        flashcall:
          $ref: '#/components/schemas/VerifyProfileFlashcallResponse'
          additionalProperties: true
          type: object
        id:
          example: 12ade33a-21c0-473b-b055-b3c836e1c292
          format: uuid
          type: string
        language:
          example: en-US
          type: string
        name:
          example: Test Profile
          type: string
        record_type:
          $ref: '#/components/schemas/VerificationProfileRecordType'
        sms:
          $ref: '#/components/schemas/VerifyProfileSMSResponse'
          additionalProperties: true
          type: object
        updated_at:
          example: '2020-09-14T17:03:32.965812'
          type: string
        webhook_failover_url:
          example: http://example.com/webhook/failover
          type: string
        webhook_url:
          example: http://example.com/webhook
          type: string
        whatsapp:
          $ref: '#/components/schemas/VerifyProfileWhatsAppResponse'
          additionalProperties: true
          type: object
      title: VerifyProfileResponse
      type: object
    VerifyProfileResponseDataWrapper:
      properties:
        data:
          $ref: '#/components/schemas/VerifyProfileResponse'
          additionalProperties: true
          type: object
      title: VerifyProfileResponseDataWrapper
      type: object
    verify_Errors:
      properties:
        errors:
          items:
            $ref: '#/components/schemas/verify_Error'
          type: array
      type: object
    VerifyProfileCallResponse:
      properties:
        app_name:
          description: The name that identifies the application requesting 2fa in the verification message.
          example: Example Secure App
          pattern: ^[A-Za-z0-9 -]{1,30}$
          type: string
        code_length:
          default: 5
          description: The length of the verify code to generate.
          example: 6
          type: integer
        default_verification_timeout_secs:
          default: 300
          description: For every request that is initiated via this Verify profile, this sets the number of seconds before a verification request code expires. Once the verification request expires, the user cannot use the code to verify their identity.
          example: 300
          type: integer
        messaging_template_id:
          description: The message template identifier selected from /verify_profiles/templates
          example: 0abb5b4f-459f-445a-bfcd-488998b7572d
          format: uuid
          type: string
        whitelisted_destinations:
          description: Enabled country destinations to send verification codes. The elements in the list must be valid ISO 3166-1 alpha-2 country codes. If set to `["*"]`, all destinations will be allowed. **Conditionally required:** this field must be provided when your organization is configured to require explicit whitelisted destinations; otherwise it is optional.
          example:
          - US
          - CA
          items:
            description: ISO 3166-1 alpha-2 country code
            pattern: ^[A-Z]{2}$
            type: string
          type: array
      title: VerifyProfileCallResponse
      type: object
    UpdateVerifyProfileCallRequest:
      properties:
        app_name:
          description: The name that identifies the application requesting 2fa in the verification message.
          example: Example Secure App
          pattern: ^[A-Za-z0-9 -]{1,30}$
          type: string
        code_length:
          default: 5
          description: The length of the verify code to generate.
          example: 6
          type: integer
        default_verification_timeout_secs:
          default: 300
          description: For every request that is initiated via this Verify profile, this sets the number of seconds before a verification request code expires. Once the verification request expires, the user cannot use the code to verify their identity.
          example: 300
          type: integer
        messaging_template_id:
          description: The message template identifier selected from /verify_profiles/templates
          example: 0abb5b4f-459f-445a-bfcd-488998b7572d
          format: uuid
          type: string
        whitelisted_destinations:
          description: Enabled country destinations to send verification codes. The elements in the list must be valid ISO 3166-1 alpha-2 country codes. If set to `["*"]`, all destinations will be allowed. **Conditionally required:** this field must be provided when your organization is configured to require explicit whitelisted destinations; otherwise it is optional.
          example:
          - US
          - CA
          items:
            description: ISO 3166-1 alpha-2 country code
            pattern: ^[A-Z]{2}$
            type: string
          type: array
      title: UpdateVerifyProfileCallRequest
      type: object
    ListVerifyProfilesResponse:
      description: A paginated list of Verify profiles
      properties:
        data:
          items:
            $ref: '#/components/schemas/VerifyProfileResponse'
          type: array
        meta:
          $ref: '#/components/schemas/verify_Meta'
      required:
      - data
      - meta
      title: ListVerifyProfilesResponse
      type: object
    UpdateVerifyProfileSMSRequest:
      properties:
        alpha_sender:
          default: Telnyx
          description: The alphanumeric sender ID to use when sending to destinations that require an alphanumeric sender ID.
          pattern: ^[A-Za-z0-9 ]{1,11}$
          type:
          - string
          - 'null'
        app_name:
          description: The name that identifies the application requesting 2fa in the verification message.
          example: Example Secure App
          pattern: ^[A-Za-z0-9 -]{1,30}$
          type: string
        code_length:
          default: 5
          description: The length of the verify code to generate.
          example: 6
          type: integer
        default_verification_timeout_secs:
          default: 300
          description: For every request that is initiated via this Verify profile, this sets the number of seconds before a verification request code expires. Once the verification request expires, the user cannot use the code to verify their identity.
          example: 300
          type: integer
        messaging_template_id:
          description: The message template identifier selected from /verify_profiles/templates
          example: 0abb5b4f-459f-445a-bfcd-488998b7572d
          format: uuid
          type: string
        whitelisted_destinations:
          description: Enabled country destinations to send verification codes. The elements in the list must be valid ISO 3166-1 alpha-2 country codes. If set to `["*"]`, all destinations will be allowed. **Conditionally required:** this field must be provided when your organization is configured to require explicit whitelisted destinations; otherwise it is optional.
          example:
          - US
          - CA
          items:
            description: ISO 3166-1 alpha-2 country code
            pattern: ^[A-Z]{2}$
            type: string
          type: array
      title: UpdateVerifyProfileSMSRequest
      type: object
    VerifyProfileMessageTemplateResponse:
      properties:
        id:
          example: 0abb5b4f-459f-445a-bfcd-488998b7572d
          format: uuid
          type: string
        text:
          example: 'Your {{app_name}} verification code is: {{code}}.'
          type: string
      title: VerifyProfileResponse
      type: object
    CreateVerifyProfileCallRequest:
      properties:
        app_name:
          description: The name that identifies the application requesting 2fa in the verification message.
          example: Example Secure App
          pattern: ^[A-Za-z0-9 -]{1,30}$
          type: string
        code_length:
          default: 5
          description: The length of the verify code to generate.
          example: 6
          type: integer
        default_verification_timeout_secs:
          default: 300
          description: For every request that is initiated via this Verify profile, this sets the number of seconds before a verification request code expires. Once the verification request expires, the user cannot use the code to verify their identity.
          example: 300
          type: integer
        messaging_template_id:
          description: The message template identifier selected from /verify_profiles/templates
          example: 0abb5b4f-459f-445a-bfcd-488998b7572d
          format: uuid
          type: string
        whitelisted_destinations:
          description: Enabled country destinations to send verification codes. The elements in the list must be valid ISO 3166-1 alpha-2 country codes. If set to `["*"]`, all destinations will be allowed. **Conditionally required:** this field must be provided when your organization is configured to require explicit whitelisted destinations; otherwise it is optional.
          example:
          - US
          - CA
          items:
            description: ISO 3166-1 alpha-2 country code
            pattern: ^[A-Z]{2}$
            type: string
          type: array
      title: CreateVerifyProfileCallRequest
      type: object
    CreateVerificationRequestCall:
      description: The request body when creating a verification.
      properties:
        custom_code:
          default: null
          description: Send a self-generated numeric code to the end-user
          example: '43612'
          type:
          - string
          - 'null'
        extension:
          default: null
          description: 'Optional extension to dial after call is answered using DTMF digits. Valid digits are 0-9, A-D, *, and #. Pauses can be added using w (0.5s) and W (1s).'
          example: 1www2WABCDw9
          type:
          - string
          - 'null'
        phone_number:
          description: +E164 formatted phone number.
          example: '+13035551234'
          type: string
        timeout_secs:
          description: The number of seconds the verification code is valid for.
          example: 300
          type: integer
        verify_profile_id:
          description: The identifier of the associated Verify profile.
          example: 12ade33a-21c0-473b-b055-b3c836e1c292
          format: uuid
          type: string
      required:
      - phone_number
      - verify_profile_id
      title: CreateVerificationRequestCall
      type: object
    MessageTemplateResponseDataWrapper:
      properties:
        data:
          $ref: '#/components/schemas/VerifyProfileMessageTemplateResponse'
      title: MessageTemplateResponseDataWrapper
      type: object
    verify_Error:
      properties:
        code:
          example: '10015'
          type: string
        detail:
          example: The value provided for sorting is not valid. Check the value used and try again.
          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: /sort
              type: string
          type: object
        title:
          example: Invalid sorting value
          type: string
      required:
      - code
      - title
      type: object
    VerificationRecordType:
      description: The possible verification record types.
      enum:
      - verification
      example: verification
      title: VerificationRecordType
      type: string
    CreateVerificationRequest:
      description: The request body when creating a verification.
      properties:
        phone_number:
          description: +E164 formatted phone number.
          example: '+13035551234'
          type: string
        timeout_secs:
          description: The number of seconds the verification code is valid for.
          example: 300
          type: integer
        verify_profile_id:
          description: The identifier of the associated Verify profile.
          example: 12ade33a-21c0-473b-b055-b3c836e1c292
          format: uuid
          type: string
      required:
      - phone_number
      - verify_profile_id
      title: CreateVerificationRequest
      type: object
    VerificationProfileRecordType:
      description: The possible verification profile record types.
      enum:
      - verification_profile
      example: verification_profile
      title: VerificationProfileRecordType
      type: string
    ListVerifyProfileMessageTemplateResponse:
      description: A list of Verify profile message templates
      properties:
        data:
          items:
            $ref: '#/components/schemas/VerifyProfileMessageTemplateResponse'
          type: array
      required:
      - data
      title: ListVerifyProfileMessageTemplateResponse
      type: object
    VerifyVerificationCodeRequestByPhoneNumber:
      properties:
        code:
          description: This is the code the user submits for verification.
          example: '17686'
          type: string
        verify_profile_id:
          description: The identifier of the associated Verify profile.
          example: 12ade33a-21c0-473b-b055-b3c836e1c292
          format: uuid
          type: string
      required:
      - code
      - verify_profile_id
      title: VerifyVerificationCodeRequestByPhoneNumber
      type: object
    VerificationType:
      description: The possible types of verification.
      enum:
      - sms
      - call
      - flashcall
      - whatsapp
      example: sms
      title: VerificationType
      type: string
    Verification:
      properties:
        created_at:
          example: '2020-09-14T17:03:32.965812'
          type: string
        custom_code:
          default: null
          description: Send a self-generated numeric code to the end-user
          example: '43612'
          type:
          - string
          - 'null'
        id:
          example: 12ade33a-21c0-473b-b055-b3c836e1c292
          format: uuid
          type: string
        phone_number:
          description: +E164 formatted phone number.
          example: '+13035551234'
          type: string
        record_type:
          $ref: '#/components/schemas/VerificationRecordType'
        status:
          $ref: '#/components/schemas/VerificationStatus'
        timeout_secs:
          description: 'This is the number of seconds before the code of the request is expired. Once this request has expired, the code will no longer verify the user. Note: this will override the `default_verification_timeout_secs` on the Verify profile.'
          example: 300
          type: integer
        type:
          $ref: '#/components/schemas/VerificationType'
        updated_at:
          example: '2020-09-14T17:03:32.965812'
          type: string
        verify_profile_id:
          description: The identifier of the associated Verify profile.
          example: 12ade33a-21c0-473b-b055-b3c836e1c292
          format: uuid
          type: string
      title: Verification
      type: object
    VerifyVerificationCodeResponse:
      properties:
        data:
          properties:
            phone_number:
              description: +E164 formatted phone number.
              example: '+13035551234'
              type: string
            response_code:
              description: Identifies if the verification code has been accepted or rejected.
              enum:
              - accepted
              - rejected
              example: accepted
              type: string
          required:
          - phone_number
          - response_code
          type: object
      required:
      - data
      title: VerifyVerificationCodeResponse
      type: object
  responses:
    verify_GenericErrorResponse:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/verify_Errors'
      description: Bad Request
  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