Vonage Verify Search API

openapi: 3.2.0
info:
  title: Vonage Verify Search 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 Search 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 Search
  description: Verify Search
paths:
  /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
      tags:
      - Verify Search
      summary: Verify Search
      parameters:
      - $ref: '#/components/parameters/format'
      - name: request_id
        required: true
        in: query
        description: The `request_id` you received in the Verify Request Response. Required if `request_ids` not provided.
        schema:
          type: string
        example: abcdef0123456789abcdef0123456789
      - name: request_ids
        required: false
        in: query
        description: More than one `request_id`. Each `request_id` is a new parameter in the Verify Search request. Required if `request_id` not provided.
        schema:
          type: array
          items:
            type: string
            example: abcdef0123456789abcdef0123456789
          maxItems: 10
        style: form
        explode: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              examples:
                success:
                  summary: The request was found
                  value:
                    request_id: abcdef0123456789abcdef0123456789
                    account_id: abcdef01
                    number: '447700900000'
                    sender_id: verify
                    date_submitted: '2020-01-01 12:00:00'
                    date_finalized: '2020-01-01 12:00:00'
                    checks:
                    - date_received: '2020-01-01 12:00:00'
                      code: '1111'
                      status: INVALID
                      ip_address: ''
                    - date_received: '2020-01-01 12:02:00'
                      code: '1234'
                      status: VALID
                      ip_address: ''
                    first_event_date: '2020-01-01 12:00:00'
                    last_event_date: '2020-01-01 12:00:00'
                    price: '0.1000000'
                    currency: EUR
                    status: SUCCESS
                    estimated_price_messages_sent: '0.06660000'
                    events:
                    - id: 0A00000012345678
                      type: sms
                    - id: 0A00000012345679
                      type: sms
                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
                not-found:
                  summary: Request not found (this also occurs immediately after completion, wait 60 seconds and try again)
                  value:
                    status: '101'
                    error_text: No response found
              schema:
                oneOf:
                - $ref: '#/components/schemas/searchResponse'
                - $ref: '#/components/schemas/searchErrorResponse'
            text/xml:
              schema:
                oneOf:
                - $ref: '#/components/schemas/searchResponse'
                - $ref: '#/components/schemas/searchErrorResponse'
    servers:
    - url: https://api.nexmo.com/verify
components:
  schemas:
    searchResponse:
      xml:
        name: verify_request
      type: object
      description: Success
      properties:
        request_id:
          type: string
          description: The `request_id` that you received in the response to the Verify request and used in the Verify search request.
          example: abcdef0123456789abcdef0123456789
        account_id:
          type: string
          description: The Vonage account ID the request was for.
          example: abcdef01
        status:
          type: string
          example: IN PROGRESS
          enum:
          - IN PROGRESS
          - SUCCESS
          - FAILED
          - EXPIRED
          - CANCELLED
          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.

            '
        number:
          type: string
          description: The phone number this verification request was used for.
          example: '447700900000'
        price:
          type: string
          description: The cost incurred for this verification request.
          example: '0.10000000'
        currency:
          type: string
          description: The currency code.
          example: EUR
        sender_id:
          type: string
          description: The `sender_id` you provided in the Verify request.
          default: verify
          example: mySenderId
        date_submitted:
          type: string
          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'
        date_finalized:
          type: string
          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'
        first_event_date:
          type: string
          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'
        last_event_date:
          type: string
          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'
        checks:
          type: array
          xml:
            wrapped: true
          description: The list of checks made for this verification and their outcomes.
          items:
            type: object
            xml:
              name: check
            properties:
              date_received:
                type: string
                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'
              code:
                type: string
                description: The code supplied with this check request
                example: '987654'
              status:
                type: string
                enum:
                - VALID
                - INVALID
              ip_address:
                type: string
                description: The IP address, if available (this field is no longer used).
                deprecated: true
                example: 123.0.0.255
        events:
          type: array
          xml:
            wrapped: true
          description: The events that have taken place to verify this number, and their unique identifiers.
          items:
            type: object
            xml:
              name: event
            properties:
              type:
                type: string
                enum:
                - tts
                - sms
              id:
                type: string
        estimated_price_messages_sent:
          $ref: '#/components/schemas/estimated_price_messages_sent'
    searchErrorResponse:
      xml:
        name: verify_request
      type: object
      description: Error
      properties:
        request_id:
          type: string
          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
        status:
          type: string
          example: IN PROGRESS
          enum:
          - IN PROGRESS
          - FAILED
          - EXPIRED
          - CANCELLED
          - '101'
          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.

            '
        error_text:
          type: string
          description: If `status` is not `SUCCESS`, this message explains the issue encountered.
          example: No response found
    estimated_price_messages_sent:
      type: string
      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'
  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