Vonage Verify Control API

openapi: 3.2.0
info:
  title: Vonage Verify Control API
  version: 1.2.4
  contact:
    name: Vonage DevRel
    email: devrel@vonage.com
    url: https://developer.nexmo.com/
  license:
    name: The MIT License (MIT)
    url: https://opensource.org/licenses/MIT
  termsOfService: https://www.nexmo.com/terms-of-use
  x-label: Deprecated
  x-metaDescription: Find quick answers to questions about the Vonage Verify API (v1.0) in this reference guide. Learn more in Vonage's API documentation.
  x-metaTitle: Vonage Verify v1.0 API Reference | Vonage API Documentation
  description: 'Operations tagged Verify Control across 2 of this provider''s published API definitions: vonage-verify-openapi.json, vonage-verify-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.nexmo.com/verify
security:
- basicAuth: []
tags:
- name: Verify Control
  description: Verify Control
paths:
  /control/{format}:
    post:
      description: 'Control the progress of your Verify requests. To cancel an existing Verify request, or to trigger the next verification event:


        1. Send a Verify control request with the appropriate command (`cmd`) for what you want to achieve.


        2. Check the `status` in the response.


        *Note that this endpoint is available by `GET` request as well as `POST`.*'
      operationId: verifyControl
      tags:
      - Verify Control
      summary: Verify Control
      parameters:
      - $ref: '#/components/parameters/format'
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/controlRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              examples:
                success-cancel:
                  summary: The request has been cancelled
                  value:
                    status: '0'
                    command: cancel
                success-trigger:
                  summary: The next event has been triggered
                  value:
                    status: '0'
                    command: trigger_next_event
                throttled:
                  summary: Request limit exceeded
                  value:
                    status: '1'
                    error_text: Throttled
                missing-param:
                  summary: Missing a parameter
                  value:
                    status: '2'
                    error_text: Missing request_id
                invalid-param:
                  summary: Invalid parameter
                  value:
                    status: '3'
                    error_text: 'Invalid value for param: request_id'
                invalid-creds:
                  summary: Invalid credentials
                  value:
                    status: '4'
                    error_text: Bad credentials
                internal-error:
                  summary: Internal Error
                  value:
                    status: '5'
                    error_text: Internal Error
                cancel-early:
                  summary: Cancellation requested less than 30 seconds into the request
                  value:
                    status: '19'
                    error_text: Verification request ['abcdef0123456789abcdef0123456789'] can't be cancelled within the first 30 seconds.
                cancel-late:
                  summary: Cancellation requested after too many retry attempts
                  value:
                    status: '19'
                    error_text: Verification request  ['abcdef0123456789abcdef0123456789'] can't be cancelled now. Too many attempts to re-deliver have already been made.
                trigger-end:
                  summary: No more events to trigger
                  value:
                    status: '19'
                    error_text: No more events are left to execute for the request ['abcdef0123456789abcdef0123456789']
              schema:
                oneOf:
                - $ref: '#/components/schemas/controlResponse'
                - $ref: '#/components/schemas/controlErrorResponse'
            text/xml:
              schema:
                oneOf:
                - $ref: '#/components/schemas/controlResponse'
                - $ref: '#/components/schemas/controlErrorResponse'
    servers:
    - url: https://api.nexmo.com/verify
components:
  schemas:
    controlResponse:
      type: object
      description: Success
      xml:
        name: response
      properties:
        status:
          type: string
          example: '0'
          description: '`cmd` | Code | Description

            -- | -- | --

            Any | 0 | Success

            '
        command:
          type: string
          description: The `cmd` you sent in the request.
          enum:
          - cancel
          - trigger_next_event
          example: cancel
    controlErrorResponse:
      type: object
      description: Error
      xml:
        name: response
      properties:
        status:
          type: string
          example: '6'
          enum:
          - '0'
          - '1'
          - '2'
          - '3'
          - '4'
          - '5'
          - '6'
          - '8'
          - '9'
          - '19'
          description: 'Code | Text | Description

            -- | -- | --

            0 | Success | The request was successfully accepted by Vonage.

            1 | Throttled | You are trying to send more than the maximum of 30 requests per second.

            2 | Your request is incomplete and missing the mandatory parameter `$parameter` | The stated parameter is missing.

            3 | Invalid value for parameter `$parameter` | Invalid value for parameter. If you see Facility not allowed in the error text, check that you are using the correct Base URL in your request.

            4 | Invalid credentials were provided | The supplied API key or secret in the request is either invalid or disabled.

            5 | Internal Error | An error occurred processing this request in the Cloud Communications Platform.

            6 | The Vonage platform was unable to process this message for the following reason: `$reason` | The request could not be routed.

            8 | The api_key you supplied is for an account that has been barred from submitting messages. |

            9 | Partner quota exceeded | Your account does not have sufficient credit to process this request.

            19 | For `cancel`: Either you have not waited at least 30 secs after sending a Verify request before cancelling or Verify has made too many attempts to deliver the verification code for this request and you must now wait for the process to complete. For `trigger_next_event`: All attempts to deliver the verification code for this request have completed and there are no remaining events to advance to.

            '
        error_text:
          type: string
          description: If the `status` is non-zero, this explains the error encountered.
          example: The requestId 'abcdef0123456789abcdef' does not exist or its no longer active.
    controlRequest:
      type: object
      required:
      - request_id
      - cmd
      properties:
        request_id:
          description: The `request_id` you received in the response to the Verify request.
          type: string
          example: abcdef0123456789abcdef0123456789
        cmd:
          description: The possible commands are `cancel` to request cancellation of the verification process, or `trigger_next_event` to advance  to the next verification event (if any). Cancellation is only possible 30 seconds after the start of the verification request and before the second event (either TTS or SMS) has taken place.
          type: string
          enum:
          - cancel
          - trigger_next_event
          example: cancel
  parameters:
    format:
      name: format
      required: true
      in: path
      description: The response format.
      schema:
        type: string
        enum:
        - json
        - xml
      example: json
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
externalDocs:
  description: More information on the Verify product on our Developer Portal
  url: https://developer.nexmo.com/verify/overview
x-refined-from:
- vonage-verify-openapi.json
- vonage-verify-openapi.yml
x-errors:
  validation:
    description: The provided payload is invalid
    resolution: 'Modify your request to provide a valid payload.

      * Minimum 8 characters

      * Maximum 25 characters

      * Minimum 1 lower case character

      * Minimum 1 upper case character

      * Minimum 1 digit

      '
    link:
      text: View API reference
      url: /api/account#createAPISecret
  delete-last-secret:
    description: You can not delete your only API secret
    resolution: Add another API secret before deleting this one