Vonage Verify Requests API

openapi: 3.2.0
info:
  title: Vonage Verify Requests 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 Requests 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 Requests
  description: Verify Requests
paths:
  /{format}:
    post:
      operationId: verifyRequest
      tags:
      - Verify Requests
      summary: Request a Verification
      description: 'Use Verify request to generate and send a PIN to your user:


        1. Create a request to send a verification code to your user.


        2. Check the `status` field in the response to ensure that your request was successful (zero is success).


        3. Use the `request_id` field in the response for the Verify check.


        *Note that this endpoint is available by `GET` request as well as `POST`.*'
      parameters:
      - $ref: '#/components/parameters/format'
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/verifyRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              examples:
                success:
                  summary: Request was started
                  value:
                    request_id: abcdef0123456789abcdef0123456789
                    status: '0'
                throttled:
                  summary: Request limit exceeded
                  value:
                    status: '1'
                    error_text: Throttled
                missing-param:
                  summary: Missing a parameter
                  value:
                    status: '2'
                    error_text: Missing brand
                invalid-param:
                  summary: Invalid parameter
                  value:
                    status: '3'
                    error_text: Invalid value for number
                invalid-creds:
                  summary: Invalid credentials
                  value:
                    status: '4'
                    error_text: Invalid credentials were provided
                internal-error:
                  summary: Internal Error
                  value:
                    status: '5'
                    error_text: Internal Error
                cannot-process:
                  summary: Unable to process message
                  value:
                    status: '6'
                    error_text: 'The Vonage platform was unable to process this message for the following reason: The request could not be routed.'
                blacklist:
                  summary: Blacklisted number
                  value:
                    status: '7'
                    error_text: The number you are trying to verify is blacklisted for verification.
                account-disabled:
                  summary: Account is barred
                  value:
                    status: '8'
                    error_text: The api_key you supplied is for an account that has been barred from submitting messages.
                quota-exceeded:
                  summary: Quota exceeded
                  value:
                    status: '9'
                    error_text: Partner quota exceeded
                concurrent:
                  summary: Concurrent verifications
                  value:
                    request_id: abcdef0123456789abcdef0123456789
                    status: '10'
                    error_text: Concurrent verifications to the same number are not allowed
                rejected:
                  summary: Rejected
                  value:
                    status: '15'
                    error_text: The destination number is not in a supported network
                not-permitted:
                  summary: Non-Permitted Destination
                  value:
                    status: '29'
                    error_text: Your Vonage account is still in demo mode. While in demo mode you must add target numbers to the approved list for your account. Add funds to your account to remove this limitation.
              schema:
                oneOf:
                - $ref: '#/components/schemas/requestResponse'
                - $ref: '#/components/schemas/requestErrorResponse'
            text/xml:
              schema:
                oneOf:
                - $ref: '#/components/schemas/requestResponse'
                - $ref: '#/components/schemas/requestErrorResponse'
    servers:
    - url: https://api.nexmo.com/verify
  /psd2/{format}:
    post:
      operationId: verifyRequestWithPSD2
      tags:
      - Verify Requests
      summary: PSD2 (Payment Services Directive 2) Request
      description: 'Use Verify request to generate and send a PIN to your user to authorize a payment:

        1. Create a request to send a verification code to your user.

        2. Check the `status` field in the response to ensure that your request was successful (zero is success).

        3. Use the `request_id` field in the response for the Verify check.

        (Please note that XML format is not supported for the Payment Services Directive endpoint at this time.)'
      parameters:
      - $ref: '#/components/parameters/format'
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/psd2Request'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/requestResponse'
                - $ref: '#/components/schemas/requestErrorResponse'
    servers:
    - url: https://api.nexmo.com/verify
components:
  parameters:
    format:
      name: format
      required: true
      in: path
      description: The response format.
      schema:
        type: string
        enum:
        - json
        - xml
      example: json
  schemas:
    requestResponse:
      type: object
      description: Success
      xml:
        name: verify_response
      properties:
        request_id:
          type: string
          description: The unique ID of the Verify request. You need this `request_id` for the Verify check.
          maxLength: 32
          example: abcdef0123456789abcdef0123456789
        status:
          type: string
          description: Indicates the outcome of the request; zero is success
          example: '0'
    verifyRequest:
      type: object
      required:
      - number
      - brand
      properties:
        number:
          type: string
          description: The mobile or landline phone number to verify. Unless you are setting `country` explicitly, this number must be in [E.164](https://en.wikipedia.org/wiki/E.164) format.
          example: '447700900000'
        country:
          description: If you do not provide `number` in international format or you are not sure if `number` is correctly formatted, specify the two-character country code in `country`. Verify will then format the number for you.
          type: string
          example: GB
        brand:
          description: 'An 18-character alphanumeric string you can use to personalize the verification request SMS body, to help users identify your company or application name. For example: "Your `Acme Inc` PIN is ..."'
          type: string
          maxLength: 18
          example: Acme Inc
        sender_id:
          description: An 11-character alphanumeric string that represents the [identity of the sender](https://developer.nexmo.com/messaging/sms/guides/custom-sender-id) of the verification request. Depending on the destination of the phone number you are sending the verification SMS to, restrictions might apply.
          type: string
          maxLength: 11
          default: VERIFY
          example: ACME
        code_length:
          description: The length of the verification code.
          type: integer
          enum:
          - 4
          - 6
          default: 4
          example: 6
        lg:
          description: 'By default, the SMS or text-to-speech (TTS) message is generated in the locale that matches the `number`. For example, the text message or TTS message for a `33*` number is sent in French. Use this parameter to explicitly control the language used for the Verify request. A list of languages is available: <https://developer.nexmo.com/verify/verify-v1/guides/verify-languages>'
          example: en-us
          type: string
          default: en-us
          enum:
          - ar-xa
          - cs-cz
          - cy-cy
          - cy-gb
          - da-dk
          - de-de
          - el-gr
          - en-au
          - en-gb
          - en-in
          - en-us
          - es-es
          - es-mx
          - es-us
          - fi-fi
          - fil-ph
          - fr-ca
          - fr-fr
          - hi-in
          - hu-hu
          - id-id
          - is-is
          - it-it
          - ja-jp
          - ko-kr
          - nb-no
          - nl-nl
          - pl-pl
          - pt-br
          - pt-pt
          - ro-ro
          - ru-ru
          - sv-se
          - th-th
          - tr-tr
          - vi-vn
          - yue-cn
          - zh-cn
          - zh-tw
        pin_expiry:
          description: How long the generated verification code is valid for, in seconds. When you specify both `pin_expiry` and `next_event_wait` then `pin_expiry` must be an integer multiple of `next_event_wait` otherwise `pin_expiry` is defaulted to equal next_event_wait. See [changing the event timings](https://developer.nexmo.com/verify/verify-v1/guides/changing-default-timings).
          type: integer
          minimum: 60
          maximum: 3600
          default: 300
          example: 240
        next_event_wait:
          description: Specifies the wait time in seconds between attempts to deliver the verification code.
          type: integer
          minimum: 60
          maximum: 900
          default: 300
          example: 120
        workflow_id:
          description: Selects the predefined sequence of SMS and TTS (Text To Speech) actions to use in order to convey the PIN to your user. For example, an id of 1 identifies the workflow SMS - TTS - TTS. For a list of all workflows and their associated ids, please visit the [developer portal](https://developer.nexmo.com/verify/verify-v1/guides/workflows-and-events).
          type: integer
          default: 1
          enum:
          - 1
          - 2
          - 3
          - 4
          - 5
          - 6
          - 7
          example: 4
        pin_code:
          type: string
          minimum: 4
          maximum: 10
          description: A custom PIN to send to the user. If a PIN is not provided, Verify will generate a random PIN for you. <b>This feature is not enabled by default</b> - please discuss with your Account Manager if you would like it enabled. If this feature is not enabled on your account, error status `20` will be returned.
          example: AKFG-3424
    psd2Request:
      type: object
      required:
      - number
      - payee
      - amount
      properties:
        number:
          type: string
          description: The mobile or landline phone number to verify. Unless you are setting `country` explicitly, this number must be in [E.164](https://en.wikipedia.org/wiki/E.164) format.
          example: '447700900000'
        country:
          description: If you do not provide `number` in international format or you are not sure if `number` is correctly formatted, specify the two-character country code in `country`. Verify will then format the number for you.
          type: string
          example: GB
        payee:
          description: An alphanumeric string to indicate to the user the name of the recipient that they are confirming a payment to.
          type: string
          maxLength: 18
          example: Acme Inc
        amount:
          description: The decimal amount of the payment to be confirmed, in Euros
          type: number
          format: float
          example: '48.00'
        code_length:
          description: The length of the verification code.
          type: integer
          enum:
          - 4
          - 6
          default: 4
          example: 6
        lg:
          description: 'By default, the SMS or text-to-speech (TTS) message is generated in the locale that matches the `number`. For example, the text message or TTS message for a `33*` number is sent in French. Use this parameter to explicitly control the language used.

            *Note: Voice calls in English for `bg-bg`, `ee-et`, `ga-ie`, `lv-lv`, `lt-lt`, `mt-mt`, `sk-sk`, `sk-si`'
          example: es-es
          type: string
          default: en-gb
          enum:
          - en-gb
          - bg-bg
          - cs-cz
          - da-dk
          - de-de
          - ee-et
          - el-gr
          - es-es
          - fi-fi
          - fr-fr
          - ga-ie
          - hu-hu
          - it-it
          - lv-lv
          - lt-lt
          - mt-mt
          - nl-nl
          - pl-pl
          - sk-sk
          - sl-si
          - sv-se
        pin_expiry:
          description: How long the generated verification code is valid for, in seconds. When you specify both `pin_expiry` and `next_event_wait` then `pin_expiry` must be an integer multiple of `next_event_wait` otherwise `pin_expiry` is defaulted to equal next_event_wait. See [changing the event timings](https://developer.nexmo.com/verify/verify-v1/guides/changing-default-timings).
          type: integer
          minimum: 60
          maximum: 3600
          default: 300
          example: 240
        next_event_wait:
          description: Specifies the wait time in seconds between attempts to deliver the verification code.
          type: integer
          minimum: 60
          maximum: 900
          default: 300
          example: 120
        workflow_id:
          description: Selects the predefined sequence of SMS and TTS (Text To Speech) actions to use in order to convey the PIN to your user. For example, an id of 1 identifies the workflow SMS - TTS - TTS. For a list of all workflows and their associated ids, please visit the [developer portal](https://developer.nexmo.com/verify/verify-v1/guides/workflows-and-events).
          type: integer
          default: 1
          enum:
          - 1
          - 2
          - 3
          - 4
          - 5
          - 6
          - 7
          example: 4
    requestErrorResponse:
      type: object
      description: Error
      xml:
        name: verify_response
      properties:
        request_id:
          type: string
          description: The unique ID of the Verify request. This may be blank in an error situation.
          maxLength: 32
          example: ''
        status:
          type: string
          example: '2'
          enum:
          - '0'
          - '1'
          - '2'
          - '3'
          - '4'
          - '5'
          - '6'
          - '7'
          - '8'
          - '9'
          - '10'
          - '15'
          - '20'
          - '29'
          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.

            7 | The number you are trying to verify is blacklisted for verification. | Returns a `network` property but no `request_id` will be present in the response.

            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.

            10 | Concurrent verifications to the same number are not allowed. | This will return a `request_id`.

            15 | The destination number is not in a supported network | The request has been rejected. Find out more about this error in the [Knowledge Base](https://api.support.vonage.com/hc/en-us/articles/360018406532-Verify-On-demand-Service-to-High-Risk-Countries)

            20 | This account does not support the parameter: pin_code. | Only certain accounts have the ability to set the `pin_code`. Please contact your account manager for more information.

            29 | Non-Permitted Destination | Your Vonage account is still in demo mode. While in demo mode you must add target numbers to the approved list for your account. Add funds to your account to remove this limitation.

            '
        error_text:
          type: string
          description: If `status` is non-zero, this explains the error encountered.
          example: Your request is incomplete and missing the mandatory parameter `number`
        network:
          type: string
          description: The Network ID of the blocking network, if relevant to the error.
          example: '244523'
  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