openapi: 3.0.3
servers:
  - url: https://api.nexmo.com/verify
info:
  contact:
    email: devrel@vonage.com
    name: Vonage DevRel
    url: https://developer.nexmo.com/
  description: |-
    The Verify API helps you to implement 2FA (two-factor authentication) in your applications. This is useful for:

    * Protecting against spam, by preventing spammers from creating multiple accounts
    * Monitoring suspicious activity, by forcing an account user to verify ownership of a number
    * Ensuring that you can reach your users at any time because you have their correct phone number
    More information is available at <https://developer.nexmo.com/verify>
  license:
    name: The MIT License (MIT)
    url: https://opensource.org/licenses/MIT
  termsOfService: https://www.nexmo.com/terms-of-use
  title: Verify API
  version: 1.2.4
  x-logo:
    url: https://www.vonage.com/content/dam/vonage/us-en/api/illustrations/Mobile_APIs_Services.svg
  x-origin:
    - format: openapi
      url: https://raw.githubusercontent.com/nexmo/api-specification/master/definitions/verify.yml
      version: "3.0"
  x-providerName: nexmo.com
  x-serviceName: verify
externalDocs:
  description: More information on the Verify product on our Developer Portal
  url: https://developer.nexmo.com/verify
tags:
  - description: Verify Requests
    name: Requests
  - description: Fraud Management
    name: Fraud Management
paths:
  /check/{format}:
    post:
      description: |-
        Use Verify check to confirm that the PIN you received from your user matches the one sent by Vonage in your Verify request.

        1. Send the verification `code` that your user supplied, with the corresponding `request_id` from the Verify request.
        2. Check the `status` of the response to determine if the code the user supplied matches the one sent by Vonage.

        *Note that this endpoint is available by `GET` request as well as `POST`.*
      operationId: verifyCheck
      parameters:
        - $ref: "#/components/parameters/format"
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: "#/components/schemas/checkRequest"
        required: true
      responses:
        "200":
          content:
            application/json:
              examples:
                incorrect-code:
                  summary: PIN code is incorrect
                  value:
                    error_text: The code inserted does not match the expected value
                    status: "16"
                internal-error:
                  summary: Internal Error
                  value:
                    error_text: Internal Error
                    status: "5"
                invalid-creds:
                  summary: Invalid credentials
                  value:
                    error_text: Bad credentials
                    status: "4"
                invalid-param:
                  summary: Invalid parameter
                  value:
                    error_text: "Invalid value for param: request_id"
                    status: "3"
                missing-param:
                  summary: Missing a parameter
                  value:
                    error_text: Missing api_key
                    status: "2"
                success:
                  summary: The supplied code is correct for this request. Verification successful.
                  value:
                    currency: EUR
                    estimated_price_messages_sent: "0.03330000"
                    event_id: 0A00000012345678
                    price: "0.10000000"
                    request_id: abcdef0123456789abcdef0123456789
                    status: "0"
                throttled:
                  summary: Request limit exceeded
                  value:
                    error_text: Throttled
                    status: "1"
                too-many-fails:
                  summary: Too many incorrect codes
                  value:
                    error_text: The wrong code was provided too many times. Request terminated
                    status: "17"
                unknown-requestid:
                  summary: This request_id is unknown or inactive
                  value:
                    error_text: "The Vonage platform was unable to process this message for the following reason: Request 'abcdef0123456789abcdef0123456789' was not found or it has been verified already."
                    status: "6"
              schema:
                oneOf:
                  - $ref: "#/components/schemas/checkResponse"
                  - $ref: "#/components/schemas/checkErrorResponse"
            text/xml:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/checkResponse"
                  - $ref: "#/components/schemas/checkErrorResponse"
          description: OK
      summary: Verify Check
  /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
      parameters:
        - $ref: "#/components/parameters/format"
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: "#/components/schemas/controlRequest"
        required: true
      responses:
        "200":
          content:
            application/json:
              examples:
                cancel-early:
                  summary: Cancellation requested less than 30 seconds into the request
                  value:
                    error_text: Verification request ['abcdef0123456789abcdef0123456789'] can't be cancelled within the first 30 seconds.
                    status: "19"
                cancel-late:
                  summary: Cancellation requested after too many retry attempts
                  value:
                    error_text: Verification request  ['abcdef0123456789abcdef0123456789'] can't be cancelled now. Too many attempts to re-deliver have already been made.
                    status: "19"
                internal-error:
                  summary: Internal Error
                  value:
                    error_text: Internal Error
                    status: "5"
                invalid-creds:
                  summary: Invalid credentials
                  value:
                    error_text: Bad credentials
                    status: "4"
                invalid-param:
                  summary: Invalid parameter
                  value:
                    error_text: "Invalid value for param: request_id"
                    status: "3"
                missing-param:
                  summary: Missing a parameter
                  value:
                    error_text: Missing api_key
                    status: "2"
                success-cancel:
                  summary: The request has been cancelled
                  value:
                    command: cancel
                    status: "0"
                success-trigger:
                  summary: The next event has been triggered
                  value:
                    command: trigger_next_event
                    status: "0"
                throttled:
                  summary: Request limit exceeded
                  value:
                    error_text: Throttled
                    status: "1"
                trigger-end:
                  summary: No more events to trigger
                  value:
                    error_text: No more events are left to execute for the request ['abcdef0123456789abcdef0123456789']
                    status: "19"
              schema:
                oneOf:
                  - $ref: "#/components/schemas/controlResponse"
                  - $ref: "#/components/schemas/controlErrorResponse"
            text/xml:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/controlResponse"
                  - $ref: "#/components/schemas/controlErrorResponse"
          description: OK
      summary: Verify Control
  /network-unblock:
    post:
      description: |-
        Request to unblock a network that has been blocked due to potential fraud detection
        <div class="Vlt-callout Vlt-callout--critical">
          <div class="Vlt-callout__content">
            <h4>Network Unblock is switched off by default.</h4>
            Please contact Sales to enable the Network Unblock API for your account.
          </div>
        </div>
      operationId: networkUnblock
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/networkUnblock"
        required: true
      responses:
        "202":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/networkUnblockResponseOk"
          description: Accepted
        "403":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/networkUnblockResponseForbidden"
          description: Forbidden
        "404":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/networkUnblockResponseNotFound"
          description: Not Found
        "422":
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/networkUnblockResponseUnprocessableNetwork"
                  - $ref: "#/components/schemas/networkUnblockResponseInvalidDuration"
          description: Unprocessable Entity
        "429":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorThrottled"
          description: Rate Limited
      summary: Request a network unblock
      tags:
        - Fraud Management
  /psd2/{format}:
    post:
      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.)
      operationId: verifyRequestWithPSD2
      parameters:
        - $ref: "#/components/parameters/format"
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: "#/components/schemas/psd2Request"
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/requestResponse"
                  - $ref: "#/components/schemas/requestErrorResponse"
          description: OK
      summary: PSD2 (Payment Services Directive 2) Request
  /search/{format}:
    get:
      description: |-
        Use Verify search to check the status of past or current verification requests:

        1. Send a Verify search request containing the `request_id`s of the verification requests you are interested in.
        2. Use the `status` of each verification request in the `checks` array of the response object to determine the outcome.

        *Note that this endpoint is available by `POST` request as well as `GET`.*
      operationId: verifySearch
      parameters:
        - $ref: "#/components/parameters/format"
        - $ref: "#/components/parameters/api_key"
        - $ref: "#/components/parameters/api_secret"
        - description: The `request_id` you received in the Verify Request Response. Required if `request_ids` not provided.
          example: abcdef0123456789abcdef0123456789
          in: query
          name: request_id
          required: true
          schema:
            type: string
        - description: More than one `request_id`. Each `request_id` is a new parameter in the Verify Search request. Required if `request_id` not provided.
          explode: true
          in: query
          name: request_ids
          required: false
          schema:
            items:
              example: abcdef0123456789abcdef0123456789
              type: string
            maxItems: 10
            type: array
          style: form
      responses:
        "200":
          content:
            application/json:
              examples:
                internal-error:
                  summary: Internal Error
                  value:
                    error_text: Internal Error
                    status: "5"
                invalid-creds:
                  summary: Invalid credentials
                  value:
                    error_text: Bad credentials
                    status: "4"
                invalid-param:
                  summary: Invalid parameter
                  value:
                    error_text: "Invalid value for param: request_id"
                    status: "3"
                missing-param:
                  summary: Missing a parameter
                  value:
                    error_text: Missing api_key
                    status: "2"
                not-found:
                  summary: Request not found (this also occurs immediately after completion, wait 60 seconds and try again)
                  value:
                    error_text: No response found
                    status: "101"
                success:
                  summary: The request was found
                  value:
                    account_id: abcdef01
                    checks:
                      - code: "1111"
                        date_received: 2020-01-01 12:00:00
                        ip_address: ""
                        status: INVALID
                      - code: "1234"
                        date_received: 2020-01-01 12:02:00
                        ip_address: ""
                        status: VALID
                    currency: EUR
                    date_finalized: 2020-01-01 12:00:00
                    date_submitted: 2020-01-01 12:00:00
                    estimated_price_messages_sent: "0.06660000"
                    events:
                      - id: 0A00000012345678
                        type: sms
                      - id: 0A00000012345679
                        type: sms
                    first_event_date: 2020-01-01 12:00:00
                    last_event_date: 2020-01-01 12:00:00
                    number: "447700900000"
                    price: "0.1000000"
                    request_id: abcdef0123456789abcdef0123456789
                    sender_id: verify
                    status: SUCCESS
                throttled:
                  summary: Request limit exceeded
                  value:
                    error_text: Throttled
                    status: "1"
              schema:
                oneOf:
                  - $ref: "#/components/schemas/searchResponse"
                  - $ref: "#/components/schemas/searchErrorResponse"
            text/xml:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/searchResponse"
                  - $ref: "#/components/schemas/searchErrorResponse"
          description: OK
      summary: Verify Search
  /{format}:
    post:
      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`.*
      operationId: verifyRequest
      parameters:
        - $ref: "#/components/parameters/format"
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: "#/components/schemas/verifyRequest"
        required: true
      responses:
        "200":
          content:
            application/json:
              examples:
                account-disabled:
                  summary: Account is barred
                  value:
                    error_text: The api_key you supplied is for an account that has been barred from submitting messages.
                    status: "8"
                blacklist:
                  summary: Blacklisted number
                  value:
                    error_text: The number you are trying to verify is blacklisted for verification.
                    status: "7"
                cannot-process:
                  summary: Unable to process message
                  value:
                    error_text: "The Vonage platform was unable to process this message for the following reason: The request could not be routed."
                    status: "6"
                concurrent:
                  summary: Concurrent verifications
                  value:
                    error_text: Concurrent verifications to the same number are not allowed
                    request_id: abcdef0123456789abcdef0123456789
                    status: "10"
                internal-error:
                  summary: Internal Error
                  value:
                    error_text: Internal Error
                    status: "5"
                invalid-creds:
                  summary: Invalid credentials
                  value:
                    error_text: Invalid credentials were provided
                    status: "4"
                invalid-param:
                  summary: Invalid parameter
                  value:
                    error_text: Invalid value for number
                    status: "3"
                missing-param:
                  summary: Missing a parameter
                  value:
                    error_text: Missing api_key
                    status: "2"
                not-permitted:
                  summary: Non-Permitted Destination
                  value:
                    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.
                    status: "29"
                quota-exceeded:
                  summary: Quota exceeded
                  value:
                    error_text: Partner quota exceeded
                    status: "9"
                rejected:
                  summary: Rejected
                  value:
                    error_text: The destination number is not in a supported network
                    status: "15"
                success:
                  summary: Request was started
                  value:
                    request_id: abcdef0123456789abcdef0123456789
                    status: "0"
                throttled:
                  summary: Request limit exceeded
                  value:
                    error_text: Throttled
                    status: "1"
              schema:
                oneOf:
                  - $ref: "#/components/schemas/requestResponse"
                  - $ref: "#/components/schemas/requestErrorResponse"
            text/xml:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/requestResponse"
                  - $ref: "#/components/schemas/requestErrorResponse"
          description: OK
      summary: Request a Verification
      tags:
        - Requests
components:
  parameters:
    api_key:
      in: query
      name: api_key
      required: true
      schema:
        $ref: "#/components/schemas/api_key"
    api_secret:
      in: query
      name: api_secret
      required: true
      schema:
        $ref: "#/components/schemas/api_secret"
    format:
      description: The response format.
      example: json
      in: path
      name: format
      required: true
      schema:
        enum:
          - json
          - xml
        type: string
  schemas:
    ErrorThrottled:
      properties:
        detail:
          description: Additional information about the error
          example: Please wait, then retry your request
          type: string
        instance:
          description: Internal Trace ID
          example: bf0ca0bf927b3b52e3cb03217e1a1ddf
          type: string
        title:
          description: Generic error message
          example: Rate Limit Hit
          type: string
        type:
          description: Link to error / remediation options
          example: https://developer.vonage.com/api-errors/verify#rate-limit
          type: string
      required:
        - type
        - title
        - detail
        - instance
      type: object
    api_key:
      description: You can find your API key in your [account dashboard](https://dashboard.nexmo.com)
      example: abcd1234
      type: string
    api_secret:
      description: You can find your API secret in your [account dashboard](https://dashboard.nexmo.com)
      example: Sup3rS3cr3t!!
      type: string
    checkErrorResponse:
      description: Error
      properties:
        error_text:
          description: If the `status` is non-zero, this explains the error encountered.
          example: The code inserted does not match the expected value
          type: string
        request_id:
          description: The `request_id` that you received in the response to the Verify request and used in the Verify check request.
          example: abcdef0123456789abcdef0123456789
          type: string
        status:
          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.
            16 | The code inserted does not match the expected value |
            17 | The wrong code was provided too many times | You can run Verify check on a specific `request_id` up to three times unless a new verification code is generated. If you check a request more than three times, it is set to FAILED and you cannot check it again.
          enum:
            - "0"
            - "1"
            - "2"
            - "3"
            - "4"
            - "5"
            - "6"
            - "16"
            - "17"
          example: "16"
          type: string
      type: object
      xml:
        name: verify_response
    checkRequest:
      properties:
        api_key:
          $ref: "#/components/schemas/api_key"
        api_secret:
          $ref: "#/components/schemas/api_secret"
        code:
          description: The verification code entered by your user.
          example: "1234"
          maxLength: 6
          minLength: 4
          type: string
        ip_address:
          deprecated: true
          description: (This field is no longer used)
          example: 123.0.0.255
          type: string
        request_id:
          description: The Verify request to check. This is the `request_id` you received in the response to the Verify request.
          example: abcdef0123456789abcdef0123456789
          maxLength: 32
          type: string
      required:
        - api_key
        - api_secret
        - request_id
        - code
      type: object
    checkResponse:
      description: Success
      properties:
        currency:
          description: The currency code.
          example: EUR
          type: string
        estimated_price_messages_sent:
          $ref: "#/components/schemas/estimated_price_messages_sent"
        event_id:
          description: The ID of the verification event, such as an SMS or TTS call.
          example: 0A00000012345678
          type: string
        price:
          description: The cost incurred for this request.
          example: "0.10000000"
          type: string
        request_id:
          description: The `request_id` that you received in the response to the Verify request and used in the Verify check request.
          example: abcdef0123456789abcdef0123456789
          type: string
        status:
          description: A value of `0` indicates that your user entered the correct code. If it is non-zero, check the `error_text`.
          example: "0"
          type: string
      type: object
      xml:
        name: verify_response
    controlErrorResponse:
      description: Error
      properties:
        error_text:
          description: If the `status` is non-zero, this explains the error encountered.
          example: The requestId 'abcdef0123456789abcdef' does not exist or its no longer active.
          type: string
        status:
          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.
          enum:
            - "0"
            - "1"
            - "2"
            - "3"
            - "4"
            - "5"
            - "6"
            - "8"
            - "9"
            - "19"
          example: "6"
          type: string
      type: object
      xml:
        name: response
    controlRequest:
      properties:
        api_key:
          $ref: "#/components/schemas/api_key"
        api_secret:
          $ref: "#/components/schemas/api_secret"
        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.
          enum:
            - cancel
            - trigger_next_event
          example: cancel
          type: string
        request_id:
          description: The `request_id` you received in the response to the Verify request.
          example: abcdef0123456789abcdef0123456789
          type: string
      required:
        - api_key
        - api_secret
        - request_id
        - cmd
      type: object
    controlResponse:
      description: Success
      properties:
        command:
          description: The `cmd` you sent in the request.
          enum:
            - cancel
            - trigger_next_event
          example: cancel
          type: string
        status:
          description: |
            `cmd` | Code | Description
            -- | -- | --
            Any | 0 | Success
          example: "0"
          type: string
      type: object
      xml:
        name: response
    estimated_price_messages_sent:
      description: |
        This field may not be present, depending on your pricing model. The
        value indicates the cost (in EUR) of the calls made and messages sent
        for the verification process. This value may be updated during and
        shortly after the request completes because user input events can
        overlap with message/call events. When this field is present, the total
        cost of the verification is the sum of this field and the `price` field.
      example: "0.03330000"
      type: string
    networkUnblock:
      properties:
        network:
          description: The Network code
          example: 32526
          type: string
        unblock_duration:
          default: 3600
          description: An optional duration the unblock will be applied for in seconds
          example: "3600"
          maximum: 86400
          minimum: 0
          required:
            - "false"
          type: integer
      type: object
    networkUnblockResponseForbidden:
      description: Forbidden
      properties:
        detail:
          description: Verbose description of the server error.
          example: Your account does not have permission to perform this action.
          type: string
        instance:
          description: The Instance ID
          example: bf0ca0bf927b3b52e3cb03217e1a1ddf
          type: string
        title:
          description: Full string text of the HTTP error code.
          example: Forbidden
          type: string
        type:
          description: A URL link to the API documentation for this type of error.
          example: https://developer.vonage.com/api-errors#forbidden
          type: string
      type: object
      xml:
        name: networkUnblockResponseForbidden
    networkUnblockResponseInvalidDuration:
      description: Invalid Duration
      properties:
        detail:
          description: Verbose description of the server error.
          example: Unblock duration is invalid.
          type: string
        instance:
          description: The Instance ID
          example: bf0ca0bf927b3b52e3cb03217e1a1ddf
          type: string
        invalid_parameters:
          description: Detailed payload of errors.
          items:
            properties:
              name:
                description: The name of the parameter.
                example: network
                type: string
              reason:
                description: The reason for the parameter error.
                example: Network not found
                type: string
            type: object
          type: array
        title:
          description: Full string text of the HTTP error code.
          example: Invalid unblock_duration parameter
          type: string
        type:
          description: A URL link to the API documentation for this type of error.
          example: https://developer.vonage.com/api-errors#invalid-paramater
          type: string
      type: object
      xml:
        name: networkUnblockResponseInvalidDuration
    networkUnblockResponseNotFound:
      description: Not Found
      properties:
        detail:
          description: Verbose description of the server error.
          example: The network you provided does not have an active block.
          type: string
        instance:
          description: InstanceID
          example: bf0ca0bf927b3b52e3cb03217e1a1ddf
          type: string
        title:
          description: Full string text of the HTTP error code.
          example: Not Found
          type: string
        type:
          description: A URL link to the API documentation for this type of error.
          example: https://developer.vonage.com/api-errors#bad-request
          type: string
      type: object
      xml:
        name: networkUnblockResponseNotFound
    networkUnblockResponseOk:
      description: Success
      properties:
        network:
          description: The unique network ID
          example: "23410"
          type: string
        unblocked_until:
          description: Gives the DateTime when the unblock will expire.
          example: 2024-04-22T08:34:58Z
          type: string
      type: object
      xml:
        name: networkUnblockResponse
    networkUnblockResponseUnprocessableNetwork:
      description: Invalid Network
      properties:
        detail:
          description: Verbose description of the server error.
          example: Network is not in the request.
          type: string
        instance:
          description: The Instance ID
          example: bf0ca0bf927b3b52e3cb03217e1a1ddf
          type: string
        invalid_parameters:
          description: Detailed payload of errors.
          items:
            properties:
              name:
                description: The name of the parameter.
                example: network
                type: string
              reason:
                description: The reason for the parameter error.
                example: Network not found
                type: string
            type: object
          type: array
        title:
          description: Full string text of the HTTP error code.
          example: Network not found.
          type: string
        type:
          description: A URL link to the API documentation for this type of error.
          example: https://developer.vonage.com/api-errors#invalid-paramater
          type: string
      type: object
      xml:
        name: networkUnblockResponseUnprocessableNetwork
    psd2Request:
      properties:
        amount:
          description: The decimal amount of the payment to be confirmed, in Euros
          example: "48.00"
          format: float
          type: number
        api_key:
          $ref: "#/components/schemas/api_key"
        api_secret:
          $ref: "#/components/schemas/api_secret"
        code_length:
          default: 4
          description: The length of the verification code.
          enum:
            - 4
            - 6
          example: 6
          type: integer
        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.
          example: GB
          type: string
        lg:
          default: en-gb
          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`
          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
          example: es-es
          type: string
        next_event_wait:
          default: 300
          description: Specifies the wait time in seconds between attempts to deliver the verification code.
          example: 120
          maximum: 900
          minimum: 60
          type: integer
        number:
          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"
          type: string
        payee:
          description: An alphanumeric string to indicate to the user the name of the recipient that they are confirming a payment to.
          example: Acme Inc
          maxLength: 18
          type: string
        pin_expiry:
          default: 300
          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/guides/changing-default-timings).
          example: 240
          maximum: 3600
          minimum: 60
          type: integer
        workflow_id:
          default: 1
          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/guides/workflows-and-events).
          enum:
            - 1
            - 2
            - 3
            - 4
            - 5
            - 6
            - 7
          example: 4
          type: integer
      required:
        - api_key
        - api_secret
        - number
        - payee
        - amount
      type: object
    requestErrorResponse:
      description: Error
      properties:
        error_text:
          description: If `status` is non-zero, this explains the error encountered.
          example: Your request is incomplete and missing the mandatory parameter `number`
          type: string
        network:
          description: The Network ID of the blocking network, if relevant to the error.
          example: "244523"
          type: string
        request_id:
          description: The unique ID of the Verify request. This may be blank in an error situation.
          example: ""
          maxLength: 32
          type: string
        status:
          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://help.nexmo.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.
          enum:
            - "0"
            - "1"
            - "2"
            - "3"
            - "4"
            - "5"
            - "6"
            - "7"
            - "8"
            - "9"
            - "10"
            - "15"
            - "20"
            - "29"
          example: "2"
          type: string
      type: object
      xml:
        name: verify_response
    requestResponse:
      description: Success
      properties:
        request_id:
          description: The unique ID of the Verify request. You need this `request_id` for the Verify check.
          example: abcdef0123456789abcdef0123456789
          maxLength: 32
          type: string
        status:
          description: Indicates the outcome of the request; zero is success
          example: "0"
          type: string
      type: object
      xml:
        name: verify_response
    searchErrorResponse:
      description: Error
      properties:
        error_text:
          description: If `status` is not `SUCCESS`, this message explains the issue encountered.
          example: No response found
          type: string
        request_id:
          description: The `request_id` that you received in the response to the Verify request and used in the Verify search request. May be empty in an error situation.
          example: abcdef0123456789abcdef0123456789
          type: string
        status:
          description: |
            Code | Description
            -- | --
            IN PROGRESS | The search is still in progress.
            SUCCESS | Your user entered a correct verification code.
            FAILED | Your user entered an incorrect code more than three times.
            EXPIRED | Your user did not enter a code before the `pin_expiry` time elapsed.
            CANCELLED | The verification process was cancelled by a Verify control request.
            101 | You supplied an invalid `request_id`, or the data is not available. Note that for recently-completed requests, there can be a delay of up to 1 minute before the results are available in search.
          enum:
            - IN PROGRESS
            - FAILED
            - EXPIRED
            - CANCELLED
            - "101"
          example: IN PROGRESS
          type: string
      type: object
      xml:
        name: verify_request
    searchResponse:
      description: Success
      properties:
        account_id:
          description: The Vonage account ID the request was for.
          example: abcdef01
          type: string
        checks:
          description: The list of checks made for this verification and their outcomes.
          items:
            properties:
              code:
                description: The code supplied with this check request
                example: "987654"
                type: string
              date_received:
                description: The date and time this check was received (in the format YYYY-MM-DD HH:MM:SS)
                example: 2020-01-01 12:00:00
                type: string
              ip_address:
                deprecated: true
                description: The IP address, if available (this field is no longer used).
                example: 123.0.0.255
                type: string
              status:
                enum:
                  - VALID
                  - INVALID
                type: string
            type: object
            xml:
              name: check
          type: array
          xml:
            wrapped: true
        currency:
          description: The currency code.
          example: EUR
          type: string
        date_finalized:
          description: The date and time the verification request was completed. This response parameter is in the following format YYYY-MM-DD HH:MM:SS.
          example: 2020-01-01 12:00:00
          type: string
        date_submitted:
          description: The date and time the verification request was submitted, in the following format YYYY-MM-DD HH:MM:SS.
          example: 2020-01-01 12:00:00
          type: string
        estimated_price_messages_sent:
          $ref: "#/components/schemas/estimated_price_messages_sent"
        events:
          description: The events that have taken place to verify this number, and their unique identifiers.
          items:
            properties:
              id:
                type: string
              type:
                enum:
                  - tts
                  - sms
                type: string
            type: object
            xml:
              name: event
          type: array
          xml:
            wrapped: true
        first_event_date:
          description: The time the first verification attempt was made, in the following format YYYY-MM-DD HH:MM:SS.
          example: 2020-01-01 12:00:00
          type: string
        last_event_date:
          description: The time the last verification attempt was made, in the following format YYYY-MM-DD HH:MM:SS.
          example: 2020-01-01 12:00:00
          type: string
        number:
          description: The phone number this verification request was used for.
          example: "447700900000"
          type: string
        price:
          description: The cost incurred for this verification request.
          example: "0.10000000"
          type: string
        request_id:
          description: The `request_id` that you received in the response to the Verify request and used in the Verify search request.
          example: abcdef0123456789abcdef0123456789
          type: string
        sender_id:
          default: verify
          description: The `sender_id` you provided in the Verify request.
          example: mySenderId
          type: string
        status:
          description: |
            Code | Description
            -- | --
            IN PROGRESS | The search is still in progress.
            SUCCESS | Your user entered a correct verification code.
            FAILED | Your user entered an incorrect code more than three times.
            EXPIRED | Your user did not enter a code before the `pin_expiry` time elapsed.
            CANCELLED | The verification process was cancelled by a Verify control request.
          enum:
            - IN PROGRESS
            - SUCCESS
            - FAILED
            - EXPIRED
            - CANCELLED
          example: IN PROGRESS
          type: string
      type: object
      xml:
        name: verify_request
    verifyRequest:
      properties:
        api_key:
          $ref: "#/components/schemas/api_key"
        api_secret:
          $ref: "#/components/schemas/api_secret"
        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 ..."'
          example: Acme Inc
          maxLength: 18
          type: string
        code_length:
          default: 4
          description: The length of the verification code.
          enum:
            - 4
            - 6
          example: 6
          type: integer
        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.
          example: GB
          type: string
        lg:
          default: en-us
          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/guides/verify-languages>"
          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
          example: en-us
          type: string
        next_event_wait:
          default: 300
          description: Specifies the wait time in seconds between attempts to deliver the verification code.
          example: 120
          maximum: 900
          minimum: 60
          type: integer
        number:
          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"
          type: string
        pin_code:
          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
          maximum: 10
          minimum: 4
          type: string
        pin_expiry:
          default: 300
          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/guides/changing-default-timings).
          example: 240
          maximum: 3600
          minimum: 60
          type: integer
        sender_id:
          default: VERIFY
          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.
          example: ACME
          maxLength: 11
          type: string
        workflow_id:
          default: 1
          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/guides/workflows-and-events).
          enum:
            - 1
            - 2
            - 3
            - 4
            - 5
            - 6
            - 7
          example: 4
          type: integer
      required:
        - api_key
        - api_secret
        - number
        - brand
      type: object
