Welcome to Nexmo Developer

We are improving our Documentation, API references, learning resources & tooling to help you more effectively use our services. We want to help you find everything you need to integrate Nexmo APIs into your code.

As we start this transition, we’d love to hear from you with thoughts & suggestions. If you’ve got something, positive or negative, to tell us, please tell us using the feedback tool at the bottom of each guide or file an issue on GitHub. - Nexmo

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.

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:

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

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