Verify API

The Verify API enables you to use 2FA (two-factor authentication) to check that you can contact a user at a specific number.

The general workflow is shown in the following sequence diagram:

Participant Your server Participant Nexmo Participant User's phone Your server-> Nexmo: 1. You request verification of a number Nexmo-->Your server: You receive the `request_id` Nexmo->User's phone: 2. Nexmo sends a verification code to \nthe user's phone number via SMS \nor text-to-speech User's phone->Your server: 3. User enters verification code into your app Your server->Nexmo: 4. You submit the `request_id` and code Nexmo-->Your server: Nexmo sends the verification result

The Verify API makes three attempts to contact the user before failing the verification process. See verification events.

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 building blocks.

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 {
    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.0.0'
Initialize your dependencies

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

Copy to Clipboard
NexmoClient client = new 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

Run your code

Save this file to your machine and run it:

$ Run using your IDE

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 handles code generation, verification and delivery via the fastest route available. You pay only for successful verifications, regardless of where your user resides.

If the user does not respond to one of two SMS within a specified time period, the Verify API sends it as a voice call using TTS (Text to Speech) 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 request.

Concepts

Building Blocks

Tutorials

Further Reading