Verify API

The Verify API enables you to confirm that you can contact a user at a specific number.

The general workflow is shown in the following sequence diagram:

Participant Nexmo Participant Your server Participant User User -> Your server: User supplies phone number Your server -> Nexmo: Request to Verify this number Nexmo --> Your server: Supply `request_id` Note right of Nexmo: Nexmo sends PIN code to user (multiple attempts as needed) Nexmo -> User: Nexmo --> User: User -> Your server: Enter PIN code Your server -> Nexmo: Check PIN is valid for `request_id` Nexmo --> Your server: OK

Getting Started

The following sample shows you how to start the verification process by sending a verification code to a user. To learn how to validate the code the user supplies and perform other operations, see the Code Snippets.

Write the code

Add the following to send-verification-code.sh:

Copy to Clipboard
curl -X GET "https://api.nexmo.com/verify/json?&api_key=$NEXMO_API_KEY&api_secret=$NEXMO_API_SECRET&number=$RECIPIENT_NUMBER&brand=AcmeInc"

View full source

Run your code

Save this file to your machine and run it:

sh send-verification-code.sh

Prerequisites

Install dependencies

npm install nexmo
Initialize your dependencies

Create a file named request.js and add the following code:

Copy to Clipboard
const Nexmo = require('nexmo');
const nexmo = new Nexmo({
  apiKey: NEXMO_API_KEY,
  apiSecret: NEXMO_API_SECRET
});

View full source

Write the code

Add the following to request.js:

Copy to Clipboard
nexmo.verify.request({
  number: RECIPIENT_NUMBER,
  brand: NEXMO_BRAND_NAME
}, (err, result) => {
  if (err) {
    console.error(err);
  } else {
    const verifyRequestId = result.request_id;
    console.log('request_id', verifyRequestId);
  }
});

View full source

Run your code

Save this file to your machine and run it:

node request.js

Prerequisites

Install dependencies

Add the following to build.gradle:

compile 'com.nexmo:client:4.3.0'
Initialize your dependencies

Create a class named StartVerification and add the following code to the main method:

Copy to Clipboard
NexmoClient client = NexmoClient.builder().apiKey(NEXMO_API_KEY).apiSecret(NEXMO_API_SECRET).build();

View full source

Write the code

Add the following to the main method of the StartVerification class:

Copy to Clipboard
VerifyResponse response = client.getVerifyClient().verify(RECIPIENT_NUMBER, "NEXMO");

if (response.getStatus() == VerifyStatus.OK) {
    System.out.printf("RequestID: %s", response.getRequestId());
} else {
    System.out.printf("ERROR! %s: %s", response.getStatus(), response.getErrorText());
}

View full source

Run your code

We can use the application plugin for Gradle to simplify the running of our application. Update your build.gradle with the following:

apply plugin: 'application'
mainClassName = project.hasProperty('main') ? project.getProperty('main') : ''

Run the following gradle command to execute your application, replacing com.nexmo.quickstart.verify with the package containing StartVerification:

gradle run -Pmain=com.nexmo.quickstart.verify.StartVerification

Prerequisites

Install dependencies

Install-Package Nexmo.Csharp.Client
Initialize your dependencies

Create a file named VerifyController.cs and add the following code:

Copy to Clipboard
var client = new Client(creds: new Nexmo.Api.Request.Credentials
{
    ApiKey = "NEXMO_API_KEY",
    ApiSecret = "NEXMO_API_SECRET"
});

View full source

Write the code

Add the following to VerifyController.cs:

Copy to Clipboard
var start = Client.NumberVerify.Verify(new NumberVerify.VerifyRequest
{
    number = RECIPIENT_NUMBER,
    brand = "AcmeInc"
});

Session["requestID"] = start.request_id;

View full source

Prerequisites

Install dependencies

composer require nexmo/client
Initialize your dependencies

Create a file named request.php and add the following code:

Copy to Clipboard
$basic  = new \Nexmo\Client\Credentials\Basic(NEXMO_API_KEY, NEXMO_API_SECRET);
$client = new \Nexmo\Client(new \Nexmo\Client\Credentials\Container($basic));

View full source

Write the code

Add the following to request.php:

Copy to Clipboard
$verification = new \Nexmo\Verify\Verification(RECIPIENT_NUMBER, 'Acme Inc');
$client->verify()->start($verification);

View full source

Run your code

Save this file to your machine and run it:

php request.php

Prerequisites

Install dependencies

pip install nexmo
Initialize your dependencies

Create a file named request.py and add the following code:

Copy to Clipboard
import nexmo

client = nexmo.Client(key=NEXMO_API_KEY, secret=NEXMO_API_SECRET)

View full source

Write the code

Add the following to request.py:

Copy to Clipboard
response = client.start_verification(number=RECIPIENT_NUMBER, brand="AcmeInc")

if response["status"] == "0":
    print("Started verification request_id is %s" % (response["request_id"]))
else:
    print("Error: %s" % response["error_text"])

View full source

Run your code

Save this file to your machine and run it:

python request.py

Prerequisites

Install dependencies

gem install nexmo
Initialize your dependencies

Create a file named request.rb and add the following code:

Copy to Clipboard
require 'nexmo'

client = Nexmo::Client.new(
  api_key: NEXMO_API_KEY,
  api_secret: NEXMO_API_SECRET
)

View full source

Write the code

Add the following to request.rb:

Copy to Clipboard
response = client.verify.request(
  number: RECIPIENT_NUMBER,
  brand: 'AcmeInc'
)

if response.status == '0'
  # display the Verify `request_id`
  puts response.request_id
else
  puts response.error_text
end

View full source

Run your code

Save this file to your machine and run it:

ruby request.rb

Features

Nexmo Verify API offers powerful default behaviour for easy integration. By default we will handle the code generation and verification, and deliver the message via the fastest route available. You can also control the user experience by defining which workflow should be used for each request; by default Nexmo will use SMS followed by TTS and another TTS in most cases.

It is possible to supply your own PIN code in some circumstances, please contact your account manager.

Delivery of the PIN code to the user uses a combination of SMS messages and TTS (Text to Speech) calls based on the user's locale. For example, the TTS for a 61* phone number is sent in English with an Australian accent (en-au). You can specify the language, accent and gender in the Verify request.

Concepts

Code Snippets

Tutorials

Further Reading