Conversion API Reference

This defines the Conversion API:

For more details, see Conversion API Overview.


A Conversion API request looks like:

This request contains:

Base URL

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


Text-To-Speech APIs


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.
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. 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=NEXMO_API_KEY
api_secret Your Secret. For example: api_secret=NEXMO_API_SECRET

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=NEXMO_API_KEY
sig The hash of the request parameters in alphabetical order, a timestamp and the signature secret. For example: sig=SIGNATURE


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


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:

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


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
402 Conversion has not been enabled for your account
420 or 423 Invalid parameters
API Value
Verify API event_id in the response to Verify Check.
SMS API message-id
Text-To-Speech API call-id
Text-To-Speech-Prompt API call-id