Nexmo

Verify: Verifying a Phone Number

The Verify API reduces what can be a complex process involving both the SMS and TTS APIs into two simple API calls. It also eliminates the need for you to generate and securely store single use codes.

A verification process can be used to verify a user's phone number during signup, or when updating a profile . It can also be used to enable second factor authentication during login. The Verify API confirms that a user is in possession of a specific device based on a phone number.

To start a verification process, you'll need the number to be verified, and a short brand so the recipient can identify . Be sure the number is in international format.

Make a call to https://api.nexmo.com/verify/json (or /xml if that's your preference), with those parameters, along with your api_key and api_secret. You can optionally select a code_length of 4 or 6 characters, and a language using the lg parameter. Should you want to change how long the code is valid, or how fast it's resent you can use the pin_expiry and next_event_wait parameters. It's also possible to restrict the verification to a mobile or a landline by using the require_type parameter. Find all the parameters in the documentation.

#!/bin/bash
curl 'https://api.nexmo.com/verify/json' \
-d api_key=API_KEY \
-d api_secret=API_SECRET \
-d number=YOUR_NUMBER \
-d brand=MyApp
<?php
$url = 'https://api.nexmo.com/verify/json?' . http_build_query([
        'api_key' => API_KEY,
        'api_secret' => API_SECRET,
        'number' => YOUR_NUMBER,
        'brand' => 'MyApp'
    ]);

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
error_log($response);
import urllib

params = {
    'api_key': API_KEY,
    'api_secret': API_SECRET,
    'number': YOUR_NUMBER,
    'brand': 'MyApp'
}

url = 'https://api.nexmo.com/verify/json?' + urllib.urlencode(params)

response = urllib.urlopen(url)
print response.read()
require "net/http"
require "uri"

uri = URI.parse("https://api.nexmo.com/verify/json")
params = {
    "api_key" => API_KEY,
    "api_secret" => API_SECRET,
    "number" => YOUR_NUMBER,
    "brand" => "MyApp"
}

response = Net::HTTP.post_form(uri, params)

puts response.body
var https = require('https');

var data = JSON.stringify({
  api_key: API_KEY,
  api_secret: API_SECRET,
  number: YOUR_NUMBER,
  brand: 'MyApp'
});

var options = {
  host: 'api.nexmo.com',
  path: '/verify/json',
  port: 443,
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Content-Length': Buffer.byteLength(data)
  }
};

var req = https.request(options);

req.write(data);
req.end();

var responseData = '';
req.on('response', function(res){
  res.on('data', function(chunk){
    responseData += chunk;
  });
  
  res.on('end', function(){
    console.log(JSON.parse(responseData));
  });
});

The response will be a JSON object (or XML) with a status. If the status is 0 the verification request was successful, and Nexmo has started the process. You can find all the status codes in the API docs. Once you've started a verification process, you can't verify the same number until the exsisting request expires.

A successful verification request will include a request_id. That will need to be used to complete the verification process.

Once the process is stated, the code should arrive to your phone as an SMS. If you wait a while, you'll also get a phone call, and the code will be read to you. The timing and channels used depends on the type of number, the country, and the carrier.

Once you have the code send that and the request_id from the initial API request to: https://api.nexmo.com/verify/json (or /xml) with your api_key and api_secret.

#!/bin/bash
curl 'https://api.nexmo.com/verify/check/json' \
-d api_key=API_KEY \
-d api_secret=API_SECRET \
-d request_id=a7d922f6a00442ee8e2f2a7646cb2a6d \
-d code=1728
<?php
$url = 'https://api.nexmo.com/verify/check/json?' . http_build_query([
        'api_key' => API_KEY,
        'api_secret' => API_SECRET,
        'request_id' => '1178e48a940a485eaca317a1237279e5',
        'code' => '6356'
    ]);

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
error_log($response);
import urllib

params = {
    'api_key': API_KEY,
    'api_secret': API_SECRET,
    'request_id': 'd945c3655d9043c0b0b3941e1144f258',
    'code': '1665'
}

url = 'https://api.nexmo.com/verify/check/json?' + urllib.urlencode(params)

response = urllib.urlopen(url)
print response.read()
require "net/http"
require "uri"

uri = URI.parse("https://api.nexmo.com/verify/check/json")
params = {
    "api_key" => API_KEY,
    "api_secret" => API_SECRET,
    "request_id" => "31d724da3286461196a82ef3eec62d2a",
    "code" => "4345"
}

response = Net::HTTP.post_form(uri, params)

puts response.body
var https = require('https');

var data = JSON.stringify({
  api_key: API_KEY,
  api_secret: API_SECRET,
  request_id: '1b770a645f4b4c9fa5fddd21dcefe0d4',
  code: '2274'
});

var options = {
  host: 'api.nexmo.com',
  path: '/verify/check/json',
  port: 443,
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Content-Length': Buffer.byteLength(data)
  }
};

var req = https.request(options);

req.write(data);
req.end();

var responseData = '';
req.on('response', function(res){
  res.on('data', function(chunk){
    responseData += chunk;
  });
  
  res.on('end', function(){
    console.log(JSON.parse(responseData));
  });
});

Again the status will be 0 if the code is correct, and the verification process successful. If not you can retry until the process times out, or you reach the maximum number of attempts.

Check out the API documentation for more on the Verify API.