Nexmo Application API

Applications V1 is deprecated

This version of the API has been deprecated. Please use version 2 going forwards

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

Download OpenAPI 3 Definition
Improve this specification

There are multiple versions of this API available

Version 1 | Version 2

Create Application

You use a POST request to create a new application.

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

Request body application/json

Key Description Example Default
api_key
Required | string

You can find your API key in your account overview

 None None
api_secret
Required | string

You can find your API secret in your account overview

 None None
name
Required | string

The name of your application.

 My Application None
type
Required | string

The Nexmo product or products that you access with this application. Currently voice and messages application types are supported.


Must be one of: voice or messages 		voice None
answer_url
string

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. Required for inbound calls only.

 https://example.com/webhooks/answer None
answer_method
string

The HTTP method used to make the request to answer_url. The default value is GET.

 GET None
event_url
string

Nexmo sends event information asynchronously to this URL when status changes for voice applications. Always required for voice applications.

 https://example.com/webhooks/event None
event_method
string

The HTTP method used to send event information to event_url. The default value is POST. For voice type applications only.

POST None
status_url
string

Nexmo sends event information asynchronously to this URL when status changes. Required for messages type applications only.

 https://example.com/webhooks/status None
status_method
string

The HTTP method used to send event information to status_url. The default value is POST. For messages type applications only.

 POST None
inbound_url
string

Nexmo sends a request to this URL when an inbound message is received. Required for messages type applications only.

 https://example.com/webhooks/inbound None
inbound_method
string

The HTTP method used to send event information to inbound_url. The default value is POST. For messages type applications only.

 POST None

View response field descriptions

Response Fields

Field Description
id
string

The ID allocated to your application by Nexmo.
name
string

The name of your application
voice
object

The Nexmo product that you access with this application.
Field Description
webhooks
array of objects
Field Description
endpoint_type
string 		One of: answer_url or event_url
endpoint
string

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. event_url: Nexmo sends event information asynchronously to this URL when status changes.
http_method
string

The HTTP method used to send event information to the event_url or answer_url.

One of: GET or POST
messages
object

The Nexmo product that you access with this application.
Field Description
webhooks
array of objects
Field Description
endpoint_type
string 		One of: inbound_url or status_url
endpoint
string

inbound_url: The URL where inbound messages are delivered. status_url: The URL where message status is delivered.
http_method
string

The HTTP method used to send data to the inbound_url or status_url. Default is POST.

One of: GET or POST
keys
object

The Nexmo product that you access with this application.
Field Description
public_key
string

The public key used to validate the JWT.
private_key
string

The private key you use to generate the JSON Web Token (JWT) that authenticates your requests to Messages API.

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

Retrieve all Applications

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

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

Query Parameter

Key Description Example Default
api_key
Required | string

You can find your API key in your account overview

 None None
api_secret
Required | string

You can find your API secret in your account overview

 None None
page_size
integer

Set the number of items returned on each call to this endpoint. The default is 10 records.

 10 10
page_index
integer

Set the offset from the first page. The default value is 0.

 0 0

View response field descriptions

Response Fields

Field Description
count
integer

The number of items associated with your account.
page_size
integer

The number of items returned on each call to this endpoint. The default is 10 records.
page_index
integer

The offset from the first page.
_embedded
object
Field Description
applications
array of objects

The collection of your applications. Each object contains information about an an individual application. The public_key is not included in the application information.
Field Description
id
string

The ID allocated to your application by Nexmo.
name
string

The name of your application
voice
object

The Nexmo product that you access with this application.
Field Description
webhooks
array of objects
Field Description
endpoint_type
string 		One of: answer_url or event_url
endpoint
string

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. event_url: Nexmo sends event information asynchronously to this URL when status changes.
http_method
string

The HTTP method used to send event information to the event_url or answer_url.

One of: GET or POST
messages
object

The Nexmo product that you access with this application.
Field Description
webhooks
array of objects
Field Description
endpoint_type
string 		One of: inbound_url or status_url
endpoint
string

inbound_url: The URL where inbound messages are delivered. status_url: The URL where message status is delivered.
http_method
string

The HTTP method used to send data to the inbound_url or status_url. Default is POST.

One of: GET or POST
keys
object

The Nexmo product that you access with this application.
Field Description
public_key
string

The public key used to validate the JWT.

 
{
  "count": 1,
  "page_size": 10,
  "page_index": 1,
  "_embedded": {
    "applications": [
      {
        "id": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
        "name": "My Application",
        "voice": {
          "webhooks": [
            {
              "endpoint_type": "answer_url",
              "endpoint": "https://example.com/webhooks/answer",
              "http_method": "GET"
            }
          ]
        },
        "messages": {
          "webhooks": [
            {
              "endpoint_type": "status_url",
              "endpoint": "https://example.com/webhooks/status",
              "http_method": "POST"
            }
          ]
        },
        "keys": {
          "public_key": "PUBLIC_KEY"
        },
        "_links": {
          "href": "/v1/applications/aaaaaaaa-bbbb-cccc-dddd-0123456789ab"
        }
      }
    ]
  },
  "_links": {
    "href": "/v1/applications/aaaaaaaa-bbbb-cccc-dddd-0123456789ab"
  }
}

Retrieve Application

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

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

Path Parameters

Key Description Example Default
app_id
Required | string

The ID allocated to your application by Nexmo.

 aaaaaaaa-bbbb-cccc-dddd-0123456789ab None

Query Parameter

Key Description Example Default
api_key
Required | string

You can find your API key in your account overview

 None None
api_secret
Required | string

You can find your API secret in your account overview

 None None

View response field descriptions

Response Fields

Field Description
id
string

The ID allocated to your application by Nexmo.
name
string

The name of your application
voice
object

The Nexmo product that you access with this application.
Field Description
webhooks
array of objects
Field Description
endpoint_type
string 		One of: answer_url or event_url
endpoint
string

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. event_url: Nexmo sends event information asynchronously to this URL when status changes.
http_method
string

The HTTP method used to send event information to the event_url or answer_url.

One of: GET or POST
messages
object

The Nexmo product that you access with this application.
Field Description
webhooks
array of objects
Field Description
endpoint_type
string 		One of: inbound_url or status_url
endpoint
string

inbound_url: The URL where inbound messages are delivered. status_url: The URL where message status is delivered.
http_method
string

The HTTP method used to send data to the inbound_url or status_url. Default is POST.

One of: GET or POST
keys
object

The Nexmo product that you access with this application.
Field Description
public_key
string

The public key used to validate the JWT.

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

Update Application

You use a PUT request to update an existing application.

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

Path Parameters

Key Description Example Default
app_id
Required | string

The ID allocated to your application by Nexmo.

 aaaaaaaa-bbbb-cccc-dddd-0123456789ab None

Request body application/json

Key Description Example Default
api_key
Required | string

You can find your API key in your account overview

 None None
api_secret
Required | string

You can find your API secret in your account overview

 None None
name
Required | string

The name of your application.

 UpdatedApplication None
type
Required | string

The Nexmo product or products that you access with this application. Currently voice and messages application types are supported. You can't change the type of application.


Must be one of: voice or messages 		voice None
answer_url
string | (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.

 https://example.com/webhooks/answer None
answer_method
string

The HTTP method used to make the request to answer_url. The default value is GET.

 GET GET
event_url
string | (url)

Nexmo sends event information asynchronously to this URL when status changes.

 https://example.com/webhooks/event None
event_method
string

The HTTP method used to send event information to event_url. The default value is POST.

 POST POST

View response field descriptions

Response Fields

Field Description
id
string

The ID allocated to your application by Nexmo.
name
string

The name of your application
voice
object

The Nexmo product that you access with this application.
Field Description
webhooks
array of objects
Field Description
endpoint_type
string 		One of: answer_url or event_url
endpoint
string

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. event_url: Nexmo sends event information asynchronously to this URL when status changes.
http_method
string

The HTTP method used to send event information to the event_url or answer_url.

One of: GET or POST
messages
object

The Nexmo product that you access with this application.
Field Description
webhooks
array of objects
Field Description
endpoint_type
string 		One of: inbound_url or status_url
endpoint
string

inbound_url: The URL where inbound messages are delivered. status_url: The URL where message status is delivered.
http_method
string

The HTTP method used to send data to the inbound_url or status_url. Default is POST.

One of: GET or POST
keys
object

The Nexmo product that you access with this application.
Field Description
public_key
string

The public key used to validate the JWT.

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

Destroy Application

You use a DELETE request to delete a single application.

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

Path Parameters

Key Description Example Default
app_id
Required | string

The ID allocated to your application by Nexmo.

 aaaaaaaa-bbbb-cccc-dddd-0123456789ab None 
No content