Vonage Verify API (via KPN)

swagger: '2.0'
info:
  title: Verify-Vonage
  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

     - **Verify Request** - Generate and send a PIN to your user. You use the request_id in the response is used for the Verify check.
     - **Verify Check** - Confirm that the PIN you received from your user matches the one sent by Vonage as a result of your Verify request.
     - **Verify Search** - Lookup the status of one or more requests.
     - **Verify Control** - Control the progress of your Verify requests.

      
    ## [Source view](https://app.swaggerhub.com/apis/kpn/verify-nexmo/)<br/>
    [Documentation view](https://app.swaggerhub.com/apis-docs/kpn/verify-nexmo/)
    
    ---
    
    ## [KPN Developer](https://developer.kpn.com/)<br/>
    [Getting Started](https://developer.kpn.com/getting-started)
    
      ---
host: api-prd.kpn.com
basePath: /communication/nexmo/verify
externalDocs:
  description: HTTP response headers
  url: https://developer.kpn.com/documentation-response-headers
schemes:
  - https

produces:
  - application
paths:
  '/':
    post:
      summary: Generate PIN
      tags:
        - Verify
      description: |-
        To use Verify Request,  follwoing steps needs to be followed
         -   Create a Request to send a PIN to your user.
         -   Check the response codes in the Response to ensure that your request was successful.
         
        ### Example
          
          Request:
          
          ```
          curl -X POST \
            'https://api-prd.kpn.com/communication/nexmo/verify' \
              -H 'authorization: Bearer access_token' \
              -H 'content-type: application/x-www-form-urlencoded' \
              -d 'number=316********&brand=VerifyTest'
          
          ```
          
          Response:
          
          ```
          {
            "request_id":"1267899",
            "status":"status",
            "error_text":"error"
          }
          
          ```
          
      consumes:
        - application/x-www-form-urlencoded

      parameters:
        - in: formData
          name: number
          description: >- 
            The mobile or landline phone number to verify. Unless you are setting country explicitly, this number must be in E.164  format. 
              example: 447700900000
          required: true
          type: string
        - in: formData
          name: brand
          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. 
              example: "Your brand PIN is ..".
          required: true
          type: string         
        - in: formData
          name: country
          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.
          required: false
          type: string      
        - in: formData
          name: sender_id
          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.
          required: false
          type: string          
        - in: formData
          name: code_length
          description: >- 
            The length of the PIN. Possible values are 6 or 4 characters. The default value is 4.
          required: false
          type: string         
        - in: formData
          name: 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 and accent used for the Verify request. The default language is en-us.
          required: false
          type: string     
        - in: formData
          name: require_type
          description: >- 
            'Restrict verification to a certain network type. Possible values are-
              All (Default)
              Mobile
              Landline
              Note- contact api_developer@kpn.com to enable this feature.'
          required: false
          type: string    
        - in: formData
          name: pin_expiry
          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. 
              For example:
                - pin_expiry = 360 seconds, so next_event_wait = 120 seconds - all three attempts have the same PIN.
                - pin_expiry = 240 seconds, so next_event_wait = 120 seconds - 1st and 2nd attempts have the same PIN, third attempt has a different PIN.
                - pin_expiry = 120 (or 200 or 400 seconds) - each attempt has a different PIN.
          required: false
          type: string       
        - in: formData
          name: next_event_wait
          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: false
          type: string             
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/VerifyRequestResponse'
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/ErrorResponse'
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/ErrorResponse'
        '403':
          description: Forbidden
          schema:
            $ref: '#/definitions/ErrorResponse'
        '404':
          description: Not Found
          schema:
            $ref: '#/definitions/ErrorResponse'
        '429':
          description: Too Many Requests
          schema:
            $ref: '#/definitions/ErrorResponse'
        '500':
          description: Server Error
          schema:
            $ref: '#/definitions/ErrorResponse'
        '503':
          description: Service Unavailable
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
        - OAuth2: []
  '/check':
    post:
      summary: Verify PIN
      tags:
        - Verify
      description: |-
        To use Check reosurce following steps need to be followed

         -  Use a check request to send the PIN you received from your user to Vonage.
         - Check the response codes in the response to see if the PIN sent by your user matched the PIN generated by Vonage
         
        ### Examples
          
          Request:
          
          ```
          curl -X POST \
            'https://api-prd.kpn.com/communication/nexmo/verify/check' \
              -H 'authorization: Bearer access_token' \
              -H 'content-type: application/x-www-form-urlencoded' \
              -d 'request_id=REQUEST_ID&code=CODE'
          
          ```
          
          
          Response:
          
          ```
          {
            "request_id":"1267899",
            "status":"status",
            "error_text":"error"
          }
          
          ```
 
      consumes:
        - application/x-www-form-urlencoded
      parameters:
        - in: formData
          name: request_id
          description: >- 
            The identifier of the Verify request to check. This is the request_id you received in the Verify Request response.
          required: true
          type: string
        - in: formData
          name: code
          description: >- 
            The PIN given by your user.
          required: true
          type: string          
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/VerifyCheckResponse'
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/ErrorResponse'
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/ErrorResponse'
        '403':
          description: Forbidden
          schema:
            $ref: '#/definitions/ErrorResponse'
        '404':
          description: Not Found
          schema:
            $ref: '#/definitions/ErrorResponse'
        '429':
          description: Too Many Requests
          schema:
            $ref: '#/definitions/ErrorResponse'
        '500':
          description: Server Error
          schema:
            $ref: '#/definitions/ErrorResponse'
        '503':
          description: Service Unavailable
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
        - OAuth2: []
  '/search':
    post:
      summary: Look up status
      tags:
        - Verify
      description: |-
        This API resource performs the following 
         - Send a Verify Search request containing the request_id's of the Verify requests to search for.
         - Check the status response parameter in the Search Response to see if the request was successfully completed.
         
         **Note :** Either `request_id` or `request_ids` can be provided as part of a request message.

         ### Example
          
          Request:
          
          ```
          curl -X POST \
            'https://api-prd.kpn.com/communication/nexmo/verify/search' \
              -H 'authorization: Bearer access_token' \
              -H 'content-type: application/x-www-form-urlencoded' \
              -d 'request_id=REQUEST_ID'
          
          ```
          
          Response:
          
          ```
          {
            "request_id":"1267899",
            "status":"status",
            "error_text":"error"
          }
          
          ```          
          
      consumes:
        - application/x-www-form-urlencoded
      parameters:   
        - in: formData
          name: request_id
          description: >- 
            `Conditional` The request_id you received in the Verify Request Response.
              (Either request_id or request_ids to be provided)
          required: false
          type: string
        - in: formData
          name: request_ids
          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.
                (Either request_id or request_ids to be provided)
          required: false
          type: string        
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/VerifySearchResponse'
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/ErrorResponse'
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/ErrorResponse'
        '403':
          description: Forbidden
          schema:
            $ref: '#/definitions/ErrorResponse'
        '404':
          description: Not Found
          schema:
            $ref: '#/definitions/ErrorResponse'
        '429':
          description: Too Many Requests
          schema:
            $ref: '#/definitions/ErrorResponse'
        '500':
          description: Server Error
          schema:
            $ref: '#/definitions/ErrorResponse'
        '503':
          description: Service Unavailable
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
        - OAuth2: []
  '/control':
    post:
      summary: Control Verify Request
      tags:
        - Verify
      description: |-
        This APi resource is used to control the progress of your Verify Requests
          - Send a Verify request.
          - Check the response.
          
          Following are possible values of "status" in the response.(Code =  Command :  Error Text : Meaning)
          
          - 0 = Success :  Success : Success.
          - 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.
          - 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.
          - 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.
          
      
          
         ### Example
        
          Request:
          
          ```
          curl -X POST \
          'https://api-prd.kpn.com/communication/nexmo/verify/control' \
            -H 'authorization: Bearer access_token' \
            -H 'content-type: application/x-www-form-urlencoded' \
            -d 'request_id=REQUEST_ID&cmd=CMD'
          
          ```
          Response:
          
          ```
          {
            "status":"0",
            "command":"cancel"
          }
          
          ```
          
      consumes:
        - application/x-www-form-urlencoded
      parameters:    
        - in: formData
          name: request_id
          description: >- 
            The request_id you received in the Verify Request Response.
          required: true
          type: string
        - in: formData
          name: cmd
          description: >- 
            Change the command workflow. Supported values are
               cancel - stop the request
               trigger_next_event - advance the request to the next part of the process.
        
              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: true
          type: string     
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/VerifyControlResponse'
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/ErrorResponse'
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/ErrorResponse'
        '403':
          description: Forbidden
          schema:
            $ref: '#/definitions/ErrorResponse'
        '404':
          description: Not Found
          schema:
            $ref: '#/definitions/ErrorResponse'
        '429':
          description: Too Many Requests
          schema:
            $ref: '#/definitions/ErrorResponse'
        '500':
          description: Server Error
          schema:
            $ref: '#/definitions/ErrorResponse'
        '503':
          description: Service Unavailable
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
        - OAuth2: []
securityDefinitions:
  OAuth2:
    type: oauth2
    tokenUrl: >-
      https://api-prd.kpn.com/oauth/client_credential/accesstoken?grant_type=client_credentials
    flow: application
definitions:
  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
            - 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 = Success. The request was successfully accepted by Vonage .
            - 4 = Throttled. You are trying to send more than the maximum of 30 requests per second.
            - 6 =Your request is incomplete and missing the mandatory parameter ($parameter). The stated parameter is missing
            - 7 = The number you are trying to verify is blacklisted for verification .
            - 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.
            - 15 = The destination number is not in a supported network. The request has been rejected.
            - 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 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
            - 18 = Too many request_ids provided. You added more than the maximum of 10 request_ids to your request.
            - 19 = No more events are left to execute for the request. 
            - 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
  VerifySearchRequest:
    type: object
    properties:
      request_id:
        type: string
        description: The request_id you received in the Verify Request Response.
        title: Request ID
      request_ids:
        type: string
        description: >-
          More than one request_id. Each request_id is a new parameter in the
          Verify Search request.
        title: Request IDs
  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 
            - IN PROGRESS =   still in progress.
            - SUCCESS = your user entered the PIN correctly. 
            - FAILED  = user entered the wrong pin more than 3 times.
            - EXPIRED =  no PIN entered during the pin_expiry time. 
            - CANCELLED = the request was cancelled using Verify Control 
            - 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
            - date_received - in YYYY-MM-DD HH:MM:SS format
            - code
            - status - possible values are  VALID and INVALID
            - ip_address
        title: List of checks
      error_text:
        type: string
        description: 'If status is not SUCCESS, this message explains the issue.'
        title: Error text
  VerifyControlRequest:
    type: object
    required:
      - request_id
      - cmd
    properties:
      request_id:
        type: string
        description: The request_id you received in the Verify Request Response.
        title: Request ID
      cmd:
        type: string
        description: |-
          Change the command workflow. Verification requests can't be cancelled within the first 30 seconds. You must wait at least 30s after sending a Verify Request before cancelling. Supported values are
            - cancel =  stop the request
            - trigger_next_event = advance the request to the next part of the process.
          
        title: command
  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
  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