Join us in San Francisco on the 29/30th of October for two days of developer workshops and technical talks

Conversion API

The Conversion API allows you to tell Nexmo about the reliability of your 2FA communications. Sending conversion data back to Nexmo enables faster and more reliable delivery of your messages.

Note: If you are using the Verify API for 2FA, you don't need to send us conversion data. The Verify API does this automatically.

Nexmo uses this conversion data, together with delivery receipts (DLRs) to facilitate Adaptive Routing™. The Adaptive Routing algorithm automatically determines the best carrier routes via which to deliver SMS and voice calls at any specific moment. In most instances, a DLR is confirmation that your message was delivered to the recipient. However, not all carriers' DLRs are reliable and some do not provide them at all. Therefore, conversion data is our best indicator of route quality.

Note: The conversion data you send us is confidential: Nexmo will never share it with third parties.

Before you send conversion data

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

When sending us conversion data you must differentiate between your 2FA messages and other communications. For example, event based alerts or marketing messages. To do this, use one API key to authenticate requests to the Conversion API for 2FA, and a different API key for everything else.

Reporting conversion data

The following diagram shows the Conversion API workflow:

#{alt_text}

To send conversion data to Nexmo:

  1. Start a 2FA workflow by sending a 2FA request

  2. Nexmo sends a text or voice message to your user.

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

  4. Immediately send a Conversion API request with information about the message identified by message-id:

    //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
    

    Important: You should always send these requests as soon as possible after your user has replied to your 2FA invitation and not wait to submit them in batches. Adaptive Routing relies on timely conversion data to make the best routing decisions.

  5. Check the response to ensure that Nexmo 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