openapi: 3.0.3
info:
  title: Vonage Communications Applications Verify API
  description: Vonage provides cloud communications APIs for voice, SMS, messaging, video, and verification. The Vonage API platform enables businesses to build communication features into applications including voice calls, SMS, video conferencing, two-factor authentication, and number management.
  version: 1.0.0
  contact:
    name: Vonage Developer Support
    url: https://api.support.vonage.com/hc/en-us
  termsOfService: https://www.vonage.com/legal/
servers:
- url: https://api.nexmo.com
  description: Vonage API Main Server
- url: https://rest.nexmo.com
  description: Vonage REST API Server
security:
- basicAuth: []
- bearerAuth: []
tags:
- name: Verify
  description: Two-factor authentication and phone verification
paths:
  /verify/{format}:
    post:
      operationId: requestVerification
      summary: Request a Verification
      description: Use Verify to ensure that you can contact a user at a specific number.
      tags:
      - Verify
      servers:
      - url: https://api.nexmo.com
      parameters:
      - name: format
        in: path
        required: true
        schema:
          type: string
          enum:
          - json
          - xml
        description: Response format.
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
              - api_key
              - api_secret
              - number
              - brand
              properties:
                api_key:
                  type: string
                api_secret:
                  type: string
                number:
                  type: string
                  description: The mobile or landline phone number to verify (E.164 format).
                brand:
                  type: string
                  description: An 18-character alphanumeric string used as the brand name in the verification message.
                code_length:
                  type: integer
                  enum:
                  - 4
                  - 6
                  default: 4
                  description: The length of the verification code.
                lg:
                  type: string
                  description: By default, the SMS or TTS message is in the language that matches the number prefix.
                workflow_id:
                  type: integer
                  description: Selects the predefined sequence of SMS and TTS (text-to-speech) actions to use.
      responses:
        '200':
          description: Verification request created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerifyResponse'
  /verify/check/{format}:
    post:
      operationId: checkVerification
      summary: Check a Verification Code
      description: Confirm whether the PIN you received from your user matches the one sent by Vonage.
      tags:
      - Verify
      servers:
      - url: https://api.nexmo.com
      parameters:
      - name: format
        in: path
        required: true
        schema:
          type: string
          enum:
          - json
          - xml
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
              - api_key
              - api_secret
              - request_id
              - code
              properties:
                api_key:
                  type: string
                api_secret:
                  type: string
                request_id:
                  type: string
                  description: The identifier of the Verify request to check.
                code:
                  type: string
                  description: The verification code entered by your user.
      responses:
        '200':
          description: Verification code checked
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerifyCheckResponse'
  /verify/search/{format}:
    get:
      operationId: searchVerification
      summary: Search Verifications
      description: Lookup the status of one or more requests.
      tags:
      - Verify
      servers:
      - url: https://api.nexmo.com
      parameters:
      - name: format
        in: path
        required: true
        schema:
          type: string
          enum:
          - json
          - xml
      - name: api_key
        in: query
        required: true
        schema:
          type: string
      - name: api_secret
        in: query
        required: true
        schema:
          type: string
      - name: request_id
        in: query
        schema:
          type: string
        description: The request ID to search for.
      responses:
        '200':
          description: Verification status retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerifySearchResponse'
  /verify/control/{format}:
    post:
      operationId: controlVerification
      summary: Control a Verification
      description: Control the progress of your Verify requests, e.g., cancel or trigger next workflow.
      tags:
      - Verify
      servers:
      - url: https://api.nexmo.com
      parameters:
      - name: format
        in: path
        required: true
        schema:
          type: string
          enum:
          - json
          - xml
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
              - api_key
              - api_secret
              - request_id
              - cmd
              properties:
                api_key:
                  type: string
                api_secret:
                  type: string
                request_id:
                  type: string
                cmd:
                  type: string
                  enum:
                  - cancel
                  - trigger_next_event
      responses:
        '200':
          description: Verification control command sent
components:
  schemas:
    VerifyResponse:
      type: object
      properties:
        request_id:
          type: string
          description: Unique identifier for the verification request.
        status:
          type: string
          description: Status code (0 = success).
        error_text:
          type: string
    VerifySearchResponse:
      type: object
      properties:
        request_id:
          type: string
        account_id:
          type: string
        status:
          type: string
        number:
          type: string
        price:
          type: string
        currency:
          type: string
        sender_id:
          type: string
        date_submitted:
          type: string
        date_finalized:
          type: string
        first_event_date:
          type: string
        last_event_date:
          type: string
        checks:
          type: array
          items:
            type: object
            properties:
              date_received:
                type: string
              code:
                type: string
              status:
                type: string
              ip_address:
                type: string
    VerifyCheckResponse:
      type: object
      properties:
        request_id:
          type: string
        event_id:
          type: string
        status:
          type: string
          description: The status of the verification request (0 = success).
        price:
          type: string
        currency:
          type: string
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: Base64-encoded API key and secret joined by a colon.
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT token for application-level authentication.