Nexmo

Verify - Nexmo

Nexmo

Verify your users with cross-channel authentication technology

Low-cost and effective verification as simple as sending an SMS

  • Identity
  • Security

API reference on SwaggerHub API reference on Postman

Introduction

The Verify API allows you to send a PIN by SMS and by phone to prove that a user can be contacted at a specific phone number. By default, the PIN is first sent via text message (SMS). If there is no reply the Verify API will then try a voice call using text-to-speech (TTS). This API can be useful for spam protection, hack protection, two-factor authentication and reaching users.

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 are 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 Nexmo.
  • 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

Setting up your third party accounts

Make sure you have a registered account on the API Store and created an application on the portal, to receive the associated client ID and secret. These are necessary to request an access token. You will receive these after your app is approved on the API Store.

Authentication

OAuth 2.0

For accessing and/or manipulating the resources, the client application (your application) needs to be granted permission to do so. The OAuth 2.0 standard defines a protocol that allows such third-party authorization through the use of access tokens. Access tokens are central in the protocol: those tokens, in the form of strings, are delivered by an authorization server (our authentication server) and they enable the client application to securely access protected data on behalf of the resource owner (the end-user). We use Client Credentials Grant which means the application makes the request to the authentication service by sending authorization credentials and the service responds with an access token among other useful information.

Get Access Token

Copy your app's credentials and replace APP_CONSUMER_KEY and APP_CONSUMER_SECRET with the copied values, then execute below curl command to receive access token.

curl -X POST \
 'https://api-prd.kpn.com/oauth/client_credential/accesstoken?grant_type=client_credentials' \
 -H 'content-type: application/x-www-form-urlencoded' \
 -d 'client_id=APP_CONSUMER_KEY&client_secret=APP_CONSUMER_SECRET'

Note: If you are using curl for Windows then please use below command.

curl -X POST "https://api-prd.kpn.com/oauth/client_credential/accesstoken?grant_type=client_credentials" -H "content-type: application/x-www-form-urlencoded" -d "client_id=APP_CONSUMER_KEY&client_secret=APP_CONSUMER_SECRET"

The authorization service returns a JSON message that contains the access token field.

{
    "refresh_token_expires_in": "0",
    "api_product_list": "[xxxxxxx]",
    "api_product_list_json": [
        " xxxxxxx"
    ],
    "organization_name": "kpn",
    "developer_email": "demo123@kpn.com",
    "token_type": "Bearer",
    "issued_at": "1521039195424",
    "client_id": "APP_CONSUMER_KEY",
    "access_token": "haf2SDl07E9N7RluNQ4kJ1TkGgso",
    "application_name": "6e38ed2d-48b1-4362-97d6-04254065d79c",
    "scope": "",
    "expires_in": "3599",
    "refresh_count": "0",
    "status": "approved"
}

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.

Result 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.

Result 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.

Result example:

{
  "request_id":"1267899",
  "status":"status",
  "error_text":"error"
}

Control verification requests

You can control the progress of your Verify Requests by filling in appropriate values. Supported values are:

  • cancel - stop the request
  • trigger_next_event - advance the request to the next part of the process

Note: 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 option as describe 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.

Result 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

API versions

Version   Description
1.0   Initial version