Nexmo

Verify - Nexmo

Nexmo

Verification as simple as sending an SMS

Protect your users and your business with all-in-one, economical verification

  • Identity
  • Security

API Button

Quick start

Make sure you’ve read Getting Started.

About

The Verify API allows you to send a PIN by SMS and 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.

How it works

To get started and test the API from your local workstation you can use Postman or our API Reference (powered by SwaggerHub) or cURL as an HTTP client. If you use the Postman collection or API Reference, make sure you update the environment settings with your credentials in order to authenticate.

 

Sequence diagram

Scroll down to see cURL examples.

Connect to the API

To start testing the API you need to get authorization credentials. Log in to your account and create a developer app on the My Apps page. The steps to create a developer app are briefly discussed under 'Support' 🡆 'Frequently Asked Questions'.

Get access token

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

You can use the same token to make multiple 'API' calls, provided the token is active. If the token expires then you can repeat this step.

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": "[Verify - Nexmo]",
    "api_product_list_json": [
        "Verify - Nexmo"
    ],
    "organization_name": "kpn",
    "developer.email": "demo123@kpn.com",
    "token_type": "BearerToken",
    "issued_at": "1521039195424",
    "client_id": "2Xvp2YLhEeT8w4cXQWvKuOpMoHQQ9zGx",
    "access_token": "haf2SDl07E9N7RluNQ4kJ1TkGgso",
    "application_name": "6e38ed2d-48b1-4362-97d6-04254065d79c",
    "scope": "",
    "expires_in": "3599",
    "refresh_count": "0",
    "status": "approved"
}

Verify Request

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

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 format is JSON.

Verify Check

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

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 format is JSON.

Verify Search

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.

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 format is JSON.

Verify Control

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

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 format is JSON.