openapi: 3.2.0
info:
  title: Vonage Verify API
  version: v1.1.1
  termsOfService: https://developer.kpn.com/legal
  contact:
    name: API Support
    email: api_developer@kpn.com
    url: https://developer.kpn.com/support
  description: "Verify API is to Verify if a phone number is valid, reachable, and accessible by the user. Verification message can be customerized. Verify API provides the following services\n\n - **Verify Request** - Generate and send a PIN to your user. You use the request_id in the response is used for the Verify check.\n - **Verify Check** - Confirm that the PIN you received from your user matches the one sent by Vonage as a result of your Verify request.\n - **Verify Search** - Lookup the status of one or more requests.\n - **Verify Control** - Control the progress of your Verify requests.\n\n  \n## [Source view](https://app.swaggerhub.com/apis/kpn/verify-nexmo/)<br/> [Documentation view](https://app.swaggerhub.com/apis-docs/kpn/verify-nexmo/)\n---\n## [KPN Developer](https://developer.kpn.com/)<br/> [Getting Started](https://developer.kpn.com/getting-started)\n\n  ---"
servers:
- url: https://api-prd.kpn.com/communication/nexmo/verify
tags:
- name: Verify
paths:
  /:
    post:
      summary: Generate PIN
      tags:
      - Verify
      description: "To use Verify Request,  follwoing steps needs to be followed\n -   Create a Request to send a PIN to your user.\n -   Check the response codes in the Response to ensure that your request was successful.\n \n### Example\n  \n  Request:\n  \n  ```\n  curl -X POST \\\n    'https://api-prd.kpn.com/communication/nexmo/verify' \\\n      -H 'authorization: Bearer access_token' \\\n      -H 'content-type: application/x-www-form-urlencoded' \\\n      -d 'number=316********&brand=VerifyTest'\n  \n  ```\n  \n  Response:\n  \n  ```\n  {\n    \"request_id\":\"1267899\",\n    \"status\":\"status\",\n    \"error_text\":\"error\"\n  }\n  \n  ```\n  "
      responses:
        '200':
          description: OK
          content:
            application:
              schema:
                $ref: '#/components/schemas/VerifyRequestResponse'
        '400':
          description: Bad Request
          content:
            application:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden
          content:
            application:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found
          content:
            application:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too Many Requests
          content:
            application:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Server Error
          content:
            application:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service Unavailable
          content:
            application:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - OAuth2: []
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              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  format. \n  example: 447700900000"
                brand:
                  type: string
                  description: "The name of the company or App you are using Verify for. This 18 character alphanumeric string is used in the body of Verify message. \n  example: \"Your brand PIN is ..\"."
                country:
                  type: string
                  description: If do not set number in international format or you are not sure if number is correctly formatted, set country with the two-character country code. For example, GB, US. Verify works out the international phone number for you.
                sender_id:
                  type: string
                  description: An 11 character alphanumeric string to specify the SenderID for SMS sent by Verify. Depending on the destination of the phone number you are applying, restrictions may apply. By default, sender_id is VERIFY.
                code_length:
                  type: string
                  description: The length of the PIN. Possible values are 6 or 4 characters. The default value is 4.
                lg:
                  type: string
                  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 and accent used for the Verify request. The default language is en-us.
                require_type:
                  type: string
                  description: "'Restrict verification to a certain network type. Possible values are-\n  All (Default)\n  Mobile\n  Landline\n  Note- contact api_developer@kpn.com to enable this feature.'"
                pin_expiry:
                  type: string
                  description: "The PIN validity time from generation. This is an integer value between 60 and 3600 seconds. The default is 300 seconds. When specified together, pin_expiry must be an integer multiple of next_event_wait. Otherwise, pin_expiry is set to equal next_event_wait. \n  For example:\n    - pin_expiry = 360 seconds, so next_event_wait = 120 seconds - all three attempts have the same PIN.\n    - pin_expiry = 240 seconds, so next_event_wait = 120 seconds - 1st and 2nd attempts have the same PIN, third attempt has a different PIN.\n    - pin_expiry = 120 (or 200 or 400 seconds) - each attempt has a different PIN."
                next_event_wait:
                  type: string
                  description: An integer value between 60 and 900 seconds inclusive that specifies the wait time between attempts to deliver the PIN. Verify calculates the default value based on the average time taken by users to complete verification.
              required:
              - number
              - brand
  /check:
    post:
      summary: Verify PIN
      tags:
      - Verify
      description: "To use Check reosurce following steps need to be followed\n\n -  Use a check request to send the PIN you received from your user to Vonage.\n - Check the response codes in the response to see if the PIN sent by your user matched the PIN generated by Vonage\n \n### Examples\n  \n  Request:\n  \n  ```\n  curl -X POST \\\n    'https://api-prd.kpn.com/communication/nexmo/verify/check' \\\n      -H 'authorization: Bearer access_token' \\\n      -H 'content-type: application/x-www-form-urlencoded' \\\n      -d 'request_id=REQUEST_ID&code=CODE'\n  \n  ```\n  \n  \n  Response:\n  \n  ```\n  {\n    \"request_id\":\"1267899\",\n    \"status\":\"status\",\n    \"error_text\":\"error\"\n  }\n  \n  ```"
      responses:
        '200':
          description: OK
          content:
            application:
              schema:
                $ref: '#/components/schemas/VerifyCheckResponse'
        '400':
          description: Bad Request
          content:
            application:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden
          content:
            application:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found
          content:
            application:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too Many Requests
          content:
            application:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Server Error
          content:
            application:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service Unavailable
          content:
            application:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - OAuth2: []
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                request_id:
                  type: string
                  description: The identifier of the Verify request to check. This is the request_id you received in the Verify Request response.
                code:
                  type: string
                  description: The PIN given by your user.
              required:
              - request_id
              - code
  /search:
    post:
      summary: Look up status
      tags:
      - Verify
      description: "This API resource performs the following \n - Send a Verify Search request containing the request_id's of the Verify requests to search for.\n - Check the status response parameter in the Search Response to see if the request was successfully completed.\n \n **Note :** Either `request_id` or `request_ids` can be provided as part of a request message.\n\n ### Example\n  \n  Request:\n  \n  ```\n  curl -X POST \\\n    'https://api-prd.kpn.com/communication/nexmo/verify/search' \\\n      -H 'authorization: Bearer access_token' \\\n      -H 'content-type: application/x-www-form-urlencoded' \\\n      -d 'request_id=REQUEST_ID'\n  \n  ```\n  \n  Response:\n  \n  ```\n  {\n    \"request_id\":\"1267899\",\n    \"status\":\"status\",\n    \"error_text\":\"error\"\n  }\n  \n  ```          \n  "
      responses:
        '200':
          description: OK
          content:
            application:
              schema:
                $ref: '#/components/schemas/VerifySearchResponse'
        '400':
          description: Bad Request
          content:
            application:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden
          content:
            application:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found
          content:
            application:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too Many Requests
          content:
            application:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Server Error
          content:
            application:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service Unavailable
          content:
            application:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - OAuth2: []
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                request_id:
                  type: string
                  description: "`Conditional` The request_id you received in the Verify Request Response.\n  (Either request_id or request_ids to be provided)"
                request_ids:
                  type: string
                  description: "`Conditional` More than one request_id. Each request_id is a new parameter in the Verify Search request. A maximum of 10 request_id parameters can be specified.\n    (Either request_id or request_ids to be provided)"
  /control:
    post:
      summary: Control Verify Request
      tags:
      - Verify
      description: "This APi resource is used to control the progress of your Verify Requests\n  - Send a Verify request.\n  - Check the response.\n  \n  Following are possible values of \"status\" in the response.(Code =  Command :  Error Text : Meaning)\n  \n  - 0 = Success :  Success : Success.\n  - 19 = Cancel  Verification requests can't be cancelled within the first 30 seconds  :  You must wait at least 30s after sending a Verify Request before cancelling.\n  - 19 =  Cancel : Verification requests can't be cancelled now. Too many attempts to re-deliver have already been made :  Verify has made too many attempts to redeliver a PIN for this request; you have to wait for the workflow to complete. Also, you cannot initiate a new Verify Request until this one expires.\n  - 19 =   Trigger_Next_Event : No more events are left to execute  : All the attempts to deliver the PIN for this request have been completed and there are no more events to skip to.\n  \n\n  \n ### Example\n\n  Request:\n  \n  ```\n  curl -X POST \\\n  'https://api-prd.kpn.com/communication/nexmo/verify/control' \\\n    -H 'authorization: Bearer access_token' \\\n    -H 'content-type: application/x-www-form-urlencoded' \\\n    -d 'request_id=REQUEST_ID&cmd=CMD'\n  \n  ```\n  Response:\n  \n  ```\n  {\n    \"status\":\"0\",\n    \"command\":\"cancel\"\n  }\n  \n  ```\n  "
      responses:
        '200':
          description: OK
          content:
            application:
              schema:
                $ref: '#/components/schemas/VerifyControlResponse'
        '400':
          description: Bad Request
          content:
            application:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden
          content:
            application:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found
          content:
            application:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too Many Requests
          content:
            application:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Server Error
          content:
            application:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service Unavailable
          content:
            application:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - OAuth2: []
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                request_id:
                  type: string
                  description: The request_id you received in the Verify Request Response.
                cmd:
                  type: string
                  description: "Change the command workflow. Supported values are\n   cancel - stop the request\n   trigger_next_event - advance the request to the next part of the process.\n\n  Verification requests can't be cancelled within the first 30 seconds. You must wait at least 30s after sending a Verify Request before cancelling."
              required:
              - request_id
              - cmd
components:
  schemas:
    VerifySearchResponse:
      type: object
      properties:
        request_id:
          type: string
          description: The request_id you received in the Verify Request Response and used in the Verify Search request.
          title: Request ID
        account_id:
          type: integer
          description: The Account ID the request was for.
          title: Account ID
        status:
          type: string
          description: "The status of the Verify Request. Possible values are following \n  - IN PROGRESS =   still in progress.\n  - SUCCESS = your user entered the PIN correctly. \n  - FAILED  = user entered the wrong pin more than 3 times.\n  - EXPIRED =  no PIN entered during the pin_expiry time. \n  - CANCELLED = the request was cancelled using Verify Control \n  - 101 = the  request_id you set in the Verify Search request is invalid."
          title: Response status
        number:
          type: string
          description: The phone number this Verify Request was made for.
          title: Phone Number
        sender_id:
          type: string
          description: The sender_id you provided in the Verify Request
          title: Sender ID
        date_submitted:
          type: string
          description: 'The date and time the Verification Request was submitted. This response parameter is in the following format YYYY-MM-DD HH:MM:SS. For example, 2012-04-05 09:22:57. '
          title: Verification request time.
        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. For example, 2012-04-05 09:22:57.
          title: Verification completed time
        first_event_date:
          type: string
          description: Time first attempt was made. This response parameter is in the following format YYYY-MM-DD HH:MM:SS. For example, 2012-04-05 09:22:57.
          title: Verification first attempt time.
        last_event_date:
          type: string
          description: 'Time last attempt was made. This response parameter is in the following format YYYY-MM-DD HH:MM:SS. For example, 2012-04-05 09:22:57. title: Verification last attempt time.'
        checks:
          type: string
          description: "The list of checks made for this verification and their outcomes. Possible values are\n  - date_received - in YYYY-MM-DD HH:MM:SS format\n  - code\n  - status - possible values are  VALID and INVALID\n  - ip_address"
          title: List of checks
        error_text:
          type: string
          description: If status is not SUCCESS, this message explains the issue.
          title: Error text
    ErrorResponse:
      type: object
      properties:
        transactionId:
          type: string
          description: transaction id of the the request
          title: Transaction ID
        status:
          type: string
          description: Status
          title: Status
        name:
          type: string
          description: Error name
          title: Error name
        message:
          type: string
          description: Error message
          title: Error message
        info:
          type: string
          description: Additional information about error
          title: Info
    VerifyRequestResponse:
      type: object
      properties:
        request_id:
          type: string
          description: The unique ID of the Verify request you sent. The value of request_id is up to 32 characters long. You use this request_id for the Verify Check.
          title: Request ID
        status:
          type: string
          example: 3161111111
          description: "The response code that explains how your request proceeded. (verify_response_codes, somevalue). Details of Status values\n  - 0 = Success. The request was successfully accepted by Vonage .\n  - 1 = Throttled. You are trying to send more than the maximum of 30 requests per second.\n  - 2 = Your request is incomplete and missing the mandatory parameter ($parameter). The stated parameter is missing.\n  - 3 = Success. The request was successfully accepted by Vonage .\n  - 4 = Throttled. You are trying to send more than the maximum of 30 requests per second.\n  - 6 =Your request is incomplete and missing the mandatory parameter ($parameter). The stated parameter is missing\n  - 7 = The number you are trying to verify is blacklisted for verification .\n  - 8 = The api_key you supplied is for an account that has been barred from submitting messages\n  - 9 = Partner quota exceeded. Your account does not have sufficient credit to process this request.\n  - 10 = Concurrent verifications to the same number are not allowed.\n  - 15 = The destination number is not in a supported network. The request has been rejected.\n  - 16 = The code inserted does not match the expected value\n  - 17 = The wrong code was provided too many times. You can run Verify Check on a request_id up to three times unless a new PIN code is generated. If you check a request more than 3 times, it is set to FAILED and you cannot check it again\n  - 18 = Too many request_ids provided. You added more than the maximum of 10 request_ids to your request.\n  - 19 = No more events are left to execute for the request. \n  - 101 = No request found. There are no matching Verify requests."
          title: status Value.
        error_text:
          type: string
          description: If status is not 0, this explains the error encountered.
          title: Error Text
    VerifyCheckResponse:
      type: object
      properties:
        event_id:
          type: string
          description: The identifier of the SMS message-id
          title: Event ID
        status:
          type: integer
          description: If the value of status is 0, your user entered the correct PIN. If it is not, check the response code.
          title: Status
        error_text:
          type: string
          description: If status is not 0, this is brief explanation about the error.
          title: Error Text
    VerifyControlResponse:
      type: object
      properties:
        request_id:
          type: string
          description: The request_id you received in the Verify Request Response and used in the Verify Search request.
          title: Request ID
        account_id:
          type: integer
          description: The Account ID the request was for.
          title: Account ID
        status:
          type: string
          description: The Verify Control Response code that explains how your request proceeded. Details of possible values are given in resource (/control) documentation.
          title: ststus
        command:
          type: string
          description: The cmd you sent in the request.
          title: Command
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        clientCredentials:
          scopes: {}
          tokenUrl: https://api-prd.kpn.com/oauth/client_credential/accesstoken?grant_type=client_credentials
externalDocs:
  description: HTTP response headers
  url: https://developer.kpn.com/documentation-response-headers