Conversion API Reference

This defines the Conversion API:

• Request - tell Nexmo if your message or call was successful
• Response - ensure that your request to the Conversion API was successful

For more details, see Conversation API Overview.

Request

A Conversion API request looks like:

https://api.nexmo.com/conversions/voice?api_key=xxxxxx&api_secret=xxxxxxx&message-id=xxxxxxxxxxxxxx&timestamp=xxxxxxxxx&delivered=true

This request contains:

• A Base URL
• Parameters
• Authentication information
• Security
• Encoding

Base URL

Conversion API only accepts POST requests. The reply is not in JSON or XML format. Your base URL becomes either:

SMS API

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

Text-To-Speech APIs

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

Parameters

Your request must contains all the parameters in the following table, otherwise it returns with a 422 or 423 errors:

Parameter	Description	Required
message-id	The ID you receive in the response to a request. Possible Values	Yes
delivered	Set to true if your user replied to the message you sent. Otherwise, set to false. Note: for curl, use 0 and 1.	Yes
timestamp	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.	Yes

Authentication information

If you are not using applications, you use the following parameters for calls to Nexmo API:

Parameter	Description
api_key	Your Key. For example: api_key=n3xm0rocks
api_secret	Your Secret. For example: api_secret=12ab34cd

Note: You find your Key and Secret in Dashboard.

If you are using signatures to verify your requests use:

Parameter	Description
api_key	Your Key. For example: api_key=n3xm0rocks
sig	The hash of the request parameters in alphabetical order, a timestamp and the signature secret. For example: sig=TwoMenWentToMowWentTOMowAMeadowT

Security

To ensure privacy, you must use HTTPS for all Nexmo API requests.

Encoding

You submit all requests with a POST or GET call using UTF-8 encoding and URL encoded values. The expected Content-Type for POST is application/x-www-form-urlencoded. For calls to a JSON endpoint, we also support:

• application/json
• application/jsonrequest
• application/x-javascript
• text/json
• text/javascript
• text/x-javascript
• text/x-json when posting parameters as a JSON object.

If you are using GET, you must set Content-Length  in the request header.

Response

The response to each request you make to the Conversion API returns the status of your request to Nexmo.

It contains following keys and values:

Key	Value
200	OK
401	Wrong credentials
420	Invalid parameters

---