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

Application API Reference

A Nexmo application contains the security and configuration information you need to connect to Nexmo endpoints and easily use our products.

Create an application

POST  https://api.nexmo.com/v1/applications

You use a POST request to create a new application:

#!/bin/bash

#Create an Application for Voice API.

  base_url='https://api.nexmo.com'
  version='/v1'
  action='/applications/?'
  key='API_KEY'
  secret='API_SECRET'
  name='MyFirstApplication'
  type='voice'
  answer_url='https://nexmo-community.github.io/ncco-examples/conference.json'
  event_url='https://example.com/call_status'

#In this example, answer_url points to a static NCCO that creates a Conference.

  curl $base_url$version$action \
    -d api_key=$key \
    -d api_secret=$secret \
    -d name=$name \
    -d type=$type \
    -d answer_url=$answer_url \
    -d event_url=$event_url

Parameters

The following table shows the parameters you use to create a new application:

Parameter Description Required
name The name of your application. Yes
type type The Nexmo product or products that you access with this application. Currently only voice is supported. Yes
answer_url The URL where your webhook delivers the Nexmo Call Control Object that governs this call. As soon as your user answers a call Nexmo makes a request to answer_url. Yes
answer_method The HTTP method used to make the request to answer_url. The default value is GET. No
event_url Nexmo sends event information asynchronously to this URL when status changes. Yes
event_method The HTTP method used to send event information to event_url. The default value is POST. No

Response

The JSON object for a 201 Created response looks like:

{
  "id": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
  "name": "My Application",
  "voice": {
    "webhooks": [
      {
        "endpoint_type": "answer_url",
        "endpoint": "https://example.com",
        "http_method": "GET"
      },
      {
        "endpoint_type": "event_url",
        "endpoint": "https://example.com",
        "http_method": "POST"
      }
    ]
  },
  "keys": {
    "public_key": "PUBLIC_KEY",
    "private_key": "PRIVATE_KEY"
  },
  "_links": {
    "self": {
      "href": "/v1/applications/aaaaaaaa-bbbb-cccc-dddd-0123456789ab"
    }
  }
}

The response contains the following keys and values:

Parameter Description
name The name of your application
type The Nexmo product or products that you access with this application. Currently only voice is supported.
id The ID allocated to your application by Nexmo.
keys.public_key The public key used to validate the JWT  .
keys.private_key The private key you use to generate the JSON Web Token (JWT) that authenticates your requests to Voice API.
answer_url The URL where your webhook delivers the Nexmo Call Control Object that governs this call. As soon as your user answers a call Nexmo makes a request to answer_url.
answer_method The HTTP method used to make the request to answer_url.
event_url Nexmo sends event information asynchronously to this URL when status changes.
event_method The HTTP method used to send event information to event_url.
_links A series of links between resources in this API in the following HAL specification  .

Retrieve your applications

GET  https://api.nexmo.com/v1/applications

You use a GET request to retrieve details of all applications associated with your account:

#!/bin/bash

base_url='https://api.nexmo.com'
version='/v1'
action='/applications/?'
key='API_KEY'
secret='API_SECRET'

curl -X GET "$base_url$version$action?api_key=$key&api_secret=$secret"

Parameters

The following table shows the parameters you use to list your apps:

Parameter Description Required
page_size Set the number of items returned on each call to this endpoint. The default is 10 records. No
page_index Set the offset from the first page. The default value is 0. No

Response

The JSON object for a 200 success response looks like:

{
  "count": 1,
  "page_size": 10,
  "page_index": 1,
  "_embedded": {
    "applications": [
      {
        "id": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
        "name": "My Application",
        "voice": {
          "webhooks": [
            {
              "endpoint_type": "event_url",
              "endpoint": "https://example.com/event",
              "http_method": "POST"
            },
            {
              "endpoint_type": "answer_url",
              "endpoint": "https://example.com/answer",
              "http_method": "GET"
            }
          ]
        },
        "keys": {
          "public_key": "PUBLIC_KEY"
        },
        "_links": {
          "self": {
            "href": "/v1/applications/aaaaaaaa-bbbb-cccc-dddd-0123456789ab"
          }
        }
      }
    ]
  },
  "_links": {
    "self": {
      "href": "/v1/applications?page_size=10&page_index=1"
    },
    "first": {
      "href": "/v1/applications?page_size=10"
    },
    "last": {
      "href": "/v1/applications?page_size=10&page_index=5"
    },
    "next": {
      "href": "/v1/applications?page_size=10&page_index=2"
    }
  }
}

The response contains:

Parameter Description
count The number of items associated with your account.
page_size Set the number of items returned on each call to this endpoint. The default is 10 records.
page_index Set the offset from the first page. The default value is 0.
applications The collection of your applications. Each object contains information about an an individual application. The public_key in not included in the application information.
_links A series of links between resources in this API in the following HAL specification  .

Retrieve an application

GET  https://api.nexmo.com/v1/applications/:app_id

You use a GET request to retrieve details about a single application:

#!/bin/bash

base_url='https://api.nexmo.com'
version='/v1'
action='/applications'
application_id='/APPLICATION_ID?'
key='API_KEY'
secret='API_SECRET'

curl -X GET "$base_url$version$action$application_id?api_key=$key&api_secret=$secret"

Response

The JSON object for a 200 OK response looks like:

{
  "id": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
  "name": "My Application",
  "voice": {
    "webhooks": [
      {
        "endpoint_type": "answer_url",
        "endpoint": "https://example.com/answer",
        "http_method": "GET"
      },
      {
        "endpoint_type": "event_url",
        "endpoint": "https://example.com/event",
        "http_method": "POST"
      }
    ]
  },
  "keys": {
    "public_key": "PUBLIC_KEY"
  },
  "_links": {
    "self": {
      "href": "/v1/applications/aaaaaaaa-bbbb-cccc-dddd-0123456789ab"
    }
  }
}

The response contains:

Parameter Description
name The name of your application
type The Nexmo product or products that you access with this application. Currently only voice is supported.
id The ID allocated to your application by Nexmo.
keys.public_key The public key used to validate the JWT  .
answer_url The URL where your webhook delivers the Nexmo Call Control Object that governs this call. As soon as your user answers a call Nexmo makes a request to answer_url.
answer_method The HTTP method used to make the request to answer_url.
event_url Nexmo sends event information asynchronously to this URL when status changes.
event_method The HTTP method used to send event information to event_url.
_links A series of links between resources in this API in the following HAL specification  .

Update an application

PUT  https://api.nexmo.com/v1/applications/:app_id

You use a PUT request to update an existing application:

#!/bin/bash

base_url='https://api.nexmo.com'
version='/v1'
action='/applications '
application_id='/APPLICATION_ID'
key='API_KEY'
secret='API_SECRET'
name='UpdatedApplication'
type='voice'
answer_url='https://example.com/ncco'
event_url='https://example.com/call_status'

#To update your application, you must include all parameters
curl -X PUT "$base_url$version$action$application_id?api_key=$key&api_secret=$secret&name=$name&type=$type&answer_url=$answer_url&event_url=$event_url"

Parameters

The following table shows the parameters you use to update an application:

Parameter Description Required
name The name of your application. Yes
type type The Nexmo product or products that you access with this application. Currently only voice is supported. Yes
answer_url The URL where your webhook delivers the Nexmo Call Control Object that governs this call. As soon as your user answers a call Nexmo makes a request to answer_url. Yes
answer_method The HTTP method used to make the request to answer_url. The default value is GET. No
event_url Nexmo sends event information asynchronously to this URL when status changes. Yes
event_method The HTTP method used to send event information to event_url. The default value is POST. No

Response

The JSON object for a 200 success response looks like:

{
  "id": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
  "name": "My Application",
  "voice": {
    "webhooks": [
      {
        "endpoint_type": "answer_url",
        "endpoint": "https://example.com/answer",
        "http_method": "GET"
      },
      {
        "endpoint_type": "event_url",
        "endpoint": "https://example.com/event",
        "http_method": "POST"
      }
    ]
  },
  "keys": {
    "public_key": "PUBLIC_KEY"
  },
  "_links": {
    "self": {
      "href": "/v1/applications/aaaaaaaa-bbbb-cccc-dddd-0123456789ab"
    }
  }
}

The response contains:

Parameter Description
name The name of your application
type The Nexmo product or products that you access with this application. Currently only voice is supported.
id The ID allocated to your application by Nexmo.
keys.public_key The public key used to validate the JWT  .
answer_url The URL where your webhook delivers the Nexmo Call Control Object that governs this call. As soon as your user answers a call Nexmo makes a request to answer_url.
answer_method The HTTP method used to make the request to answer_url.
event_url Nexmo sends event information asynchronously to this URL when status changes.
event_method The HTTP method used to send event information to event_url.
_links A series of links between resources in this API in the following HAL specification  .

Destroy an Application

DELETE  https://api.nexmo.com/v1/applications/:id

You use a DELETE request to delete a single application:

#!/bin/bash

base_url='https://api.nexmo.com'
version='/v1'
action='/applications '
application_id='/APPLICATION_ID'
key='API_KEY'
secret='API_SECRET'

curl -X DELETE "$base_url$version$action$application_id?api_key=$key&api_secret=$secret"

Response

Nexmo returns a 204 No Content status code when your application is successfully deleted.