Introduction

Nexmo is now called Vonage, but there are still references to Nexmo in our URLs, code snippets and message templates.

Vonage's (formerly called Nexmo) Verify API can be used for two-factor authentication, spam protection, hack protection and reaching users.

It sends a PIN via SMS text message and by telephone to verify user identity by proving that a user can be contacted at a specific telephone number. By default, the PIN is first sent via SMS. If there is no reply Vonage's Verify API will then try a voice call using text-to-speech (TTS).


API specification

Test the API on SwaggerHub


Base URL

https://api-prd.kpn.com/communication/nexmo/verify


Conceptual model

Conceptual model


Definitions

PIN

A secret code that is only known by the issuer and yourself. The issuer uses and validates the PIN to verify if it's actually you they are communicating with.

SMS

SMS stands for Short Message Service and is the most widely used type of text messaging. With an SMS, you can send a message of up to 160 characters to another device.

TTS

Abbreviation for Text-To-Speech. Written text is spoken by a computer-generated synthesized voice.

E.164

E.164 defines a general format for international telephone numbers. Plan-conforming numbers are limited to a maximum of 15 digits, excluding the international call prefix.


API workflow

API workflow


Features and constraints

Features

  • Authentication by mobile phone by SMS.
  • Option to cancel the request.
  • Check if the received user response is actually the same as the PIN sent by Vonage.
  • If no response is send from the user, the system will call the user and tell the PIN.

Constraints

  • After a verify request is sent, your application has to retrieve the PIN from the user and check it by means of an additional API call.


Getting started

Make sure you've read Getting Started for more info on how to register your application and start trying out our APIs.

Authentication

The API follows the KPN Store API Authentication Standard to secure the API. It includes the use of OAuth 2.0 client_id and client_secret to receive an access token.

Go to the Authentication tab on top of this page to find out how to:

  • Authenticate to an API using cURL.
  • Authenticate to an API on Swaggerhub.
  • Import Open API Specifications (OAS), also called Swagger files into Postman.


How to...

Send a verification request

Send a verification code to a user phone to start a one-time password, two-factor authentication or phone verification process.

SwaggerHub:

  1. Select POST /.
  2. Click 'Try it out'.
  3. Fill out the parameters number and brand with the telephone number (in E.164 format) and your brand message before the PIN.
  4. Click 'Execute'.
  5. Check the response code and message.

Postman:

  1. Select (POST) Verify Request.
  2. Select the Verify-Nexmo environment from the environment selector.
  3. Open the environment and edit variables number and brand with the telephone number (in E.164 format) and your brand message before the PIN.
  4. Click 'Send'.
  5. Check the response code and message.
^^Response example^^
{
  "request_id":"1267899",
  "status":"status",
  "error_text":"error"
}

Check a verification

Check a verification code that a user has provided. Use the request_id from the response message that was received when the verification code was sent with the check.

SwaggerHub:

  1. Select POST /check.
  2. Click 'Try it out'.
  3. Fill out the parameters request_id and code with request_id as returned from the previous request and the PIN that the user of the mobile phone provided you.
  4. Click 'Execute'.
  5. Check the response code and message.

Postman:

  1. Select (POST) Verify Check.
  2. Select the Verify-Nexmo environment from the environment selector.
  3. Open the environment and edit variables request_id and code with the request_id as returned from the previous request and the PIN that the user of the mobile phone provided you.
  4. Click 'Send'.
  5. Check the response code and message.
^^Response example^^
{
  "request_id":"1267899",
  "status":"status",
  "error_text":"error"
}

Search verification requests

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.

SwaggerHub:

  1. Select POST /search.
  2. Click 'Try it out'.
  3. Fill out the parameters request_id with the request_id as returned from the initial request.
  4. Click 'Execute'.
  5. Check the response code and message.

Postman:

  1. Select (POST) Verify Search.
  2. Select the Verify-Nexmo environment from the environment selector.
  3. Open the environment edit variables request_id with the request_id as returned from the initial request.
  4. Click 'Send'.
  5. Check the response code and message.
^^Response example^^
{
  "request_id":"1267899",
  "status":"status",
  "error_text":"error"
}

Control verification requests

You can control the progress of your Verify Requests by filling in the appropriate values. 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 canceled within the first 30 seconds. You must wait at least 30 seconds after sending a Verify Request before canceling.

SwaggerHub:

  1. Select POST /control.
  2. Click 'Try it out'.
  3. Fill out the parameters request_id and cmd with the request_id as returned from the initial request and one of the command options as described above.
  4. Click 'Execute'.
  5. Check the response code and message.

Postman:

  1. Select (POST) Verify Control.
  2. Select the Verify-Nexmo environment from the environment selector.
  3. Open the environment edit variables request_id and cmd with the request_id as returned from the initial request and one of the command option as describe above.
  4. Click 'Send'.
  5. Check the response code and message.
^^Response example^^
{
  "request_id":"1267899",
  "status":"status",
  "error_text":"error"
}


Return codes

Code Description
200 Success.
201 Created.
202 Accepted.
302 Found. Link in location header.
400 Bad request.
401 Unauthorized.
403 Forbidden.
404 Not found.
405 Method not allowed.
412 Precondition failed.
429 Too many requests.
500 Internal server error.
502 Bad gateway.
503 Service unavailable.


HTTP response headers

The following tables display the standard response headers that are returned with each API response:

Standard response field name Description
sunset This field will be populated with the deprecation details. By default the value is n/a.
api-version Indicates the API version you have used.
quota-interval Used to specify an integer (for example, 1, 2, 5, 60, and so on) that will be paired with the quota-time-unit you specify (minute, hour, day, week, or month) to determine a time period during which the quota use is calculated.
For example, an interval of 24 with a quota-time-unit of hour means that the quota will be calculated over the course of 24 hours.
quota-limit Number of API calls an user can make within a given time period.
If this limit is exceeded, the user will be throttled and API requests will fail.
quota-reset-UTC All quota times are set to the Coordinated Universal Time (UTC) time zone.
quota-time-unit Used to specify the unit of time applicable to the quota.
For example, an interval of 24 with a quota-time-unit of hour means that the quota will be calculated over the course of 24 hours.
quota-used Number of API calls made within the quota.
strict-transport-security The HTTP Strict-Transport-Security (HSTS) response header lets a web site tell browsers that it should only be accessed using HTTPS, instead of using HTTP. All present and future subdomains will be HTTPS for a maximum of 1 year and access is blocked to pages or sub domains that can only be served over HTTP including HSTS preload lists of web browsers.
Strict-Transport-Security: max-age=31536000; includeSubDomains; preload.
Access control field name Description
access-control-allow-credentials Tells browsers whether to expose the response to frontend JavaScript samp when the request's credentials mode (Request.credentials) is include.
When a request's credentials mode (Request.credentials) is include, browsers will only expose the response to frontend JavaScript samp if the Access-Control-Allow-Credentials value is true. Boolean.
access-control-allow-origin Indicates whether the response can be shared with requesting samp from the given origin.
access-control-allow-headers Used in response to a pre-flight request which includes the Access-Control-Request-Headers to indicate which HTTP headers can be used during the actual request.
access-control-max-age Indicates how long the results of a pre-flight request (that is the information contained in the Access-Control-Allow-Methods and Access-Control-Allow-Headers headers) can be cached.
access-control-allow-methods Indicates which HTTP methods are allowed on a particular endpoint for cross-origin requests.
For example: GET, PUT, POST, DELETE.
content-length The Content-Length entity header indicates the size of the entity-body, in bytes, sent to the recipient.
content-type The Content-Type entity header the client what the content type of the returned content actually is.

Mopinion feedback