Developer API

You use the REST Developer API to buy credit or phone numbers, check your account balance and update your profile without having to sign into Dashboard.

A Developer API request looks like:<action>/api_key=xxxxxxxx&api_secret=xxxxxxxx&to=xxxxxxxxxxxx

This request contains:

Base URL

All requests to Developer API must contain:

  • A response object: json or xml - You must set the Accept HTTP header in your request, if the Accepts HTTP header specifies the application/json content type with higher priority than application/xml then content is returned as JSON.


Possible actions are:

Function Name Description
Account Get Balance Retrieve your current account balance.
  Pricing Retrieve our outbound pricing for a given country.
  Settings Update your account settings.
  TopUp Top-up an account that is configured for auto reload.
  Numbers Retrieve all the phone numbers associated with your account.
Numbers Search Retrieve the list of virtual numbers available for a specific country.
  Buy Rent a specific virtual number.
  Cancel Cancel your rental of a specific virtual number.
  Update You make a POST request change the webhook endpoints associated with a rented virtual number or associate a virtual number with an Application.
Search Message Search for a message by MessageID.
  Messages Search for more than one message by MessageID.
  Rejections Search for the messages rejected on a certain day and time.

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

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


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.
Previous   Next