Verify API

You use the Verify API to send a PIN by SMS or Text-To-Speech in order to prove that a user can be contacted at a specific phone number.

Verifying phone numbers is a mission-critical process you use for:

  • SPAM Protection - prevent spammers from mass-creating messages
  • Hack protection - if you detect suspicious or significant activities, validate that the person using a phone number owns it
  • Reach Users - ensure you have the correct phone number to contact your user when you need to

By default, the PIN is first sent in an SMS, if there is no reply Verify sends a TTS. TTS are sent in the locale that matches the phone number. For example, the TTS for a 61* phone number is sent using an Australian accent for the English language (en-au). You can explicitly control the language, accent and gender in TTS from the Verify Request.

Using Verify API, the workflow to confirm that your user can be contacted at a specific phone number is:

workflow_verify_api

To Verify that a phone number is valid, reachable, and accessible by your user:

  1. Verify Request: ask Nexmo to generate and send a PIN to your user. You use the request_id in the Response for the Verify Check.
    <?php
    $url = 'https://api.nexmo.com/verify/json?' . http_build_query([
            'api_key' => 'API_KEY',
            'api_secret' => 'API_SECRET',
            'number' => '441632960960',
            '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': '441632960960',
        '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' => '441632960960',
        '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: '441632960960',
      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));
      });
    });
    
  2. Nexmo sends a PIN to your user.
    The default this PIN is valid for 300 seconds after generation. To change this value, use the pin_expiry and next_event_wait parameters in your Verify Request.
  3. Your user enters the PIN in your app.
  4. Verify Check: confirm that the PIN you received from your user matches the one sent by Nexmo after your Verify Request:
    <?php
    $url = 'https://api.nexmo.com/verify/check/json?' . http_build_query([
            'api_key' => 'API_KEY',
            'api_secret' => 'API_SECRET',
            'request_id' => 'ID_RETURNED_IN_THE_VERIFY_RESPONSE',
            'code' => 'APIN'
        ]);
    
    $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': 'ID_RETURNED_IN_THE_VERIFY_RESPONSE',
        'code': 'APIN'
    }
    
    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' => 'ID_RETURNED_IN_THE_VERIFY_RESPONSE',
        'code' => 'APIN'
    }
    
    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: 'ID_RETURNED_IN_THE_VERIFY_RESPONSE',
      code: 'APIN'
    });
    
    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));
      });
    });
    
    You can run Verify Check on a Verify request_id up to three times unless a new PIN code is generated. If you check a request more than 3 times, it is set to FAILED and you cannot check it again.

To cancel or advance the Verify workflow, use Verify Control. To lookup the status of one or more Verify requests, call Verify Search.

Note: you can asily integrate Verify functionality into your Android, iOS or JavaScript App with Verify SDK.

Previous   Next