Conversion API

The Conversion API allows you to tell Nexmo about the reliability of your 2FA communications. Sending conversion data back to us means that Nexmo can deliver messages faster and more reliably.

The conversion data you send us is confidential: Nexmo does not share it with third parties.

In order to identify the carriers who provide the best performance, Nexmo continually tests the routes we use to deliver SMS and voice calls. Using Adaptive Routingā„¢, Nexmo actively reroutes messages through different carrier routes and ensures faster and more reliable delivery for your messages. The route choice is made using millions of real-time conversion data points.

Message delivery indicators are:

When you are implementing Conversion API you must differentiate between your 2FA traffic and other messages. For example, Event Based Alerts or marketing messages. To do this, use one api_key to authenticate requests to Conversion API for 2FA traffic, and a different api_key for everything else.

Note: to rapidly integrate 2FA into your app, use Verify API. The Conversion API is already integrated into Verify for fast and reliable delivery of your content.

The following figure shows the Conversion API workflow:

#{alt_text}

Access to the Conversion API is not enabled by default when you create your Nexmo account. To use Conversion API, you must first request access in an email to support@nexmo.com.

Once you have access, to use Conversion API:

  1. Start a 2FA workflow using either:

    1. SMS API
    2. Text-to-Speech Prompt APIĀ 
  2. Nexmo sends a text or voice message to your user.

  3. Your user replies to your message or verification request.

  4. As soon as possible, send a Conversion API request with information about the Call or Text-To-Speech identified by message-id. Nexmo uses your conversion data and internal information about message-id to help improve our routing of messages in the future.

    //You use the information you received in response from a request to SMS API or Call API.
    
    var https = require('https');
    
    var data = JSON.stringify({
     api_key: 'API_KEY',
     api_secret: 'API_SECRET',
     message-id: message-id,
     timestamp: yyyy-MM-dd HH:mm:ss,
     delivered: true_or_false
    });
    
    var options = {
     host: 'api.nexmo.com',
     path: '/conversions/sms',
     port: 443,
     method: 'POST'
    };
    
    var req = https.request(options);
    
    req.write(data);
    req.end();
    
    var responseData = '';
    req.on('response', function(res){
     res.on('data', function(chunk){
       responseData += chunk;
     });
    
    });
    
    <?php
    //You use the information you received in response from a request to SMS API or Call API.
      $url = 'https://api.nexmo.com/conversions/sms?' . http_build_query([
              'api_key' => 'API_KEY',
              'api_secret' => 'API_SECRET',
              'message-id'=> message-id,
              'timestamp'=> yyyy-MM-dd HH:mm:ss,
              'delivered'=> true_or_false
          ]);
    
      $ch = curl_init($url);
      curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
      curl_setopt($ch, CURLOPT_HEADER, 1);
      $response = curl_exec($ch);
      $header_size = curl_getinfo($ch, CURLINFO_HEADER_SIZE);
      $header = substr($response, 0, $header_size);
      if (strpos($header, '201')){
        echo ("Success");
      }
    }
    
    import urllib
    
    #You use the information you received in response from a request to SMS API or Call API.
    
    params = {
        'api_key': 'API_KEY',
        'api_secret': 'API_SECRET',
        'message-id': THE_ID_FROM_THE_RESPONSE,
        'timestamp': IN_UTC_yyyy-MM-dd HH:mm:ss,
        'delivered': true_or_false
    }
    
    url = 'https://api.nexmo.com/conversions/sms?' + urllib.urlencode(params)
    
    response = urllib.urlopen(url)
    print response.read()
    
    require "net/http"
    require "uri"
    
    #You use the information you received in response from a request to SMS API or Call API.
    
    uri = URI.parse("https://api.nexmo.com/conversions/sms?")
    params = {
        "api_key" => 'API_KEY',
        "api_secret" => 'API_SECRET',
        "message-id" => THE_ID_FROM_THE_RESPONSE,
        "timestamp" => IN_UTC_yyyy-MM-dd HH:mm:ss,
        "delivered" => true_or_false
    }
    
    response = Net::HTTP.post_form(uri, params)
    
    puts response.body
    
  5. Check the Response to see if we successfully received your conversion data.

    if (!error && response.statusCode == 200) {
      console.log("success") ;
    }
    
    
    <?php
      //Check if the conversion data was delivered successfully
      $header_size = curl_getinfo($ch, CURLINFO_HEADER_SIZE);
      $header = substr($response, 0, $header_size);
      if (strpos($header, '201')){
        echo ("Success");
      }
    
    if response.code == 200 :
      print "success"
    
    if response.kind_of? Net::HTTPOK
      puts "Success"
    end