Nexmo 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.

Download OpenAPI 3 Definition
Improve this specification

SMS Conversion

SMS Conversion Request

Tell Nexmo if your SMS message was successful

Send a Conversion API request with information about the SMS message 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.

POST https://api.nexmo.com/conversions/sms

Query Parameter

Key Description Example Default
api_key
apiKey

You can find your API key in your account overview

 abc123 None
api_secret
apiKey

You can find your API secret in your account overview

 abc123 None
sig
apiKey

The hash of the request parameters in alphabetical order, a timestamp and the signature secret. For example: sig=SIGNATURE

 abc123 None
message-id
Required | string

The ID you receive in the response to a request. * From the Verify API - use the event_id in the response to Verify Check. * From the SMS API - use the message-id * From the Text-To-Speech API - use the call-id * From the Text-To-Speech-Prompt API - use the call-id

 00A0B0C0 None
delivered
Required

Set to true if your user replied to the message you sent. Otherwise, set to false. Note: for curl, use 0 and 1.


Must be one of: true, false, 0 or 1 		true None
timestamp
Required | string

When the user completed your call-to-action (e.g. visited your website, installed your app) in UTC±00:00 format: yyyy-MM-dd HH:mm:ss. If you do not set this parameter, Nexmo uses the time it receives this request.

 2020-01-01 12:00:00 None 
OK
Wrong credentials
Conversion has not been enabled for your account
Invalid parameters
Invalid parameters

Voice Conversion

Voice Conversion Request

Tell Nexmo if your voice call was successful

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.

POST https://api.nexmo.com/conversions/voice

Query Parameter

Key Description Example Default
api_key
apiKey

You can find your API key in your account overview

 abc123 None
api_secret
apiKey

You can find your API secret in your account overview

 abc123 None
sig
apiKey

The hash of the request parameters in alphabetical order, a timestamp and the signature secret. For example: sig=SIGNATURE

 abc123 None
message-id
Required | string

The ID you receive in the response to a request. * From the Verify API - use the event_id in the response to Verify Check. * From the SMS API - use the message-id * From the Text-To-Speech API - use the call-id * From the Text-To-Speech-Prompt API - use the call-id

 00A0B0C0 None
delivered
Required

Set to true if your user replied to the message you sent. Otherwise, set to false. Note: for curl, use 0 and 1.


Must be one of: true, false, 0 or 1 		true None
timestamp
Required | string

When the user completed your call-to-action (e.g. visited your website, installed your app) in UTC±00:00 format: yyyy-MM-dd HH:mm:ss. If you do not set this parameter, Nexmo uses the time it receives this request.

 2020-01-01 12:00:00 None 
OK
Wrong credentials
Conversion has not been enabled for your account
Invalid parameters
Invalid parameters