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 Conversion API Overview.


A Conversion API request looks like:

This request contains:

Base URL

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.
If you do not set this parameter, Nexmo uses the time it receives this request.

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:

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


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