Available Operations
 
 

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.

Available Operations:

There are multiple versions of this API available

Version 1 | Version 2

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
Host https://api.nexmo.com
GET /v1/applications

Query Parameter

api_key
string | Required

You can find your API key in your account overview

api_secret
string | Required

You can find your API secret in your account overview

page_size
integer

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

page_index
integer

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

Responses

200 OK
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
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.

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.

webhooks
array of objects
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.

webhooks
array of objects
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.

public_key
string

The public key used to validate the JWT.

Example Responses

200
{
  "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"
  }
}

Create Application

You use a POST request to create a new application.

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

Request body application/json

api_key
string | Required

You can find your API key in your account overview

api_secret
string | Required

You can find your API secret in your account overview

name
string | Required

The name of your application.

type
string | Required

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

answer_method
string

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

event_url
string

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

event_method
string

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

status_url
string

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

status_method
string

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

inbound_url
string

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

inbound_method
string

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

Responses

201 Created
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.

webhooks
array of objects
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.

webhooks
array of objects
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.

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.

Example Request

{
  "api_key": "ap1k3y",
  "api_secret": "230e6cf0709417176df1b4fc1e083adc",
  "name": "My Application",
  "type": "voice"
}
{
  "api_key": "ap1k3y",
  "api_secret": "230e6cf0709417176df1b4fc1e083adc",
  "name": "My Application",
  "type": "voice",
  "answer_url": "https://example.com/webhooks/answer",
  "answer_method": "GET",
  "event_url": "https://example.com/webhooks/event",
  "event_method": "POST",
  "status_url": "https://example.com/webhooks/status",
  "status_method": "POST",
  "inbound_url": "https://example.com/webhooks/inbound",
  "inbound_method": "POST"
}

Example Responses

201
{
  "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 Application

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

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

Path Parameters

app_id
string | Required

The ID allocated to your application by Nexmo.

Query Parameter

api_key
string | Required

You can find your API key in your account overview

api_secret
string | Required

You can find your API secret in your account overview

Responses

200 OK
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.

webhooks
array of objects
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.

webhooks
array of objects
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.

public_key
string

The public key used to validate the JWT.

Example Responses

200
{
  "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
Host https://api.nexmo.com
PUT /v1/applications/:app_id

Path Parameters

app_id
string | Required

The ID allocated to your application by Nexmo.

Request body application/json

api_key
string | Required

You can find your API key in your account overview

api_secret
string | Required

You can find your API secret in your account overview

name
string | Required

The name of your application.

type
string | Required

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

answer_method
string

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

event_url
string (url)

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

event_method
string

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

Responses

200 OK
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.

webhooks
array of objects
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.

webhooks
array of objects
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.

public_key
string

The public key used to validate the JWT.

Example Request

{
  "api_key": "ap1k3y",
  "api_secret": "230e6cf0709417176df1b4fc1e083adc",
  "name": "UpdatedApplication",
  "type": "voice"
}
{
  "api_key": "ap1k3y",
  "api_secret": "230e6cf0709417176df1b4fc1e083adc",
  "name": "UpdatedApplication",
  "type": "voice",
  "answer_url": "https://example.com/webhooks/answer",
  "answer_method": "GET",
  "event_url": "https://example.com/webhooks/event",
  "event_method": "POST"
}

Example Responses

200
{
  "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
Host https://api.nexmo.com
DELETE /v1/applications/:app_id

Path Parameters

app_id
string | Required

The ID allocated to your application by Nexmo.

Example Responses

204
No content