Nexmo Application API

Version 1

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 Specification
Available Operations

Retrieve all Applications

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

gethttps://api.nexmo.com/v1/applications/

Query Parameters

api_key
string

You can find your API key in your account overview

api_secret
string

You can find your API secret in your account overview

page_size
integer
Default10

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
Content Type
application/json

OK

count
integer
Required
example1

The number of items associated with your account.

page_size
integer
Required
example10

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

page_index
integer
Required
example1

The offset from the first page.

_embedded
object
Required
applications
array

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
exampleaaaaaaaa-bbbb-cccc-dddd-0123456789ab

The ID allocated to your application by Nexmo.

name
string
Required
exampleMy Application

The name of your application

voice
object
Required

The Nexmo product that you access with this application.

webhooks
array
endpoint_type
string
Required
exampleanswer_url
Must be one of:answer_urlevent_url
endpoint
string(url)
Required
examplehttps://example.com/webhooks/answer

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

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

Must be one of:GETPOST
messages
object
Required

The Nexmo product that you access with this application.

webhooks
array
endpoint_type
string
Required
examplestatus_url
Must be one of:inbound_urlstatus_url
endpoint
string(url)
Required
examplehttps://example.com/webhooks/status

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

http_method
string
Required
examplePOST

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

Must be one of:GETPOST
keys
object

The Nexmo product that you access with this application.

public_key
string
examplePUBLIC_KEY

The public key used to validate the JWT.

_links
object

A series of links between resources in this API in the following HAL specification.

href
string(url)
example/v1/applications/aaaaaaaa-bbbb-cccc-dddd-0123456789ab

The link URL.

_links
object
Required

A series of links between resources in this API in the following HAL specification.

href
string(url)
example/v1/applications/aaaaaaaa-bbbb-cccc-dddd-0123456789ab

The link URL.

Example Response

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

posthttps://api.nexmo.com/v1/applications/

Request Body
Content Type
application/json

api_key
string
Required
exampleap1k3y

You can find your API key in your account overview

api_secret
string
Required
example230e6cf0709417176df1b4fc1e083adc

You can find your API secret in your account overview

name
string
Required
exampleMy Application

The name of your application.

type
string
Required
examplevoice

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

Must be one of:voicemessages
answer_url
string
examplehttps://example.com/webhooks/answer

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
exampleGET

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

event_url
string
examplehttps://example.com/webhooks/event

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

event_method
string
examplePOST

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

status_url
string
examplehttps://example.com/webhooks/status

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

status_method
string
examplePOST

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

inbound_url
string
examplehttps://example.com/webhooks/inbound

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

inbound_method
string
examplePOST

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

Example Request

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

Responses
Content Type
application/json

Created

id
string
exampleaaaaaaaa-bbbb-cccc-dddd-0123456789ab

The ID allocated to your application by Nexmo.

name
string
Required
exampleMy Application

The name of your application

voice
object
Required

The Nexmo product that you access with this application.

webhooks
array
endpoint_type
string
Required
exampleanswer_url
Must be one of:answer_urlevent_url
endpoint
string(url)
Required
examplehttps://example.com/webhooks/answer

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

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

Must be one of:GETPOST
messages
object
Required

The Nexmo product that you access with this application.

webhooks
array
endpoint_type
string
Required
examplestatus_url
Must be one of:inbound_urlstatus_url
endpoint
string(url)
Required
examplehttps://example.com/webhooks/status

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

http_method
string
Required
examplePOST

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

Must be one of:GETPOST
keys
object

The Nexmo product that you access with this application.

public_key
string
examplePUBLIC_KEY

The public key used to validate the JWT.

private_key
string
examplePRIVATE_KEY

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

_links
object

A series of links between resources in this API in the following HAL specification.

href
string(url)
example/v1/applications/aaaaaaaa-bbbb-cccc-dddd-0123456789ab

The link URL.

Example Response

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

gethttps://api.nexmo.com/v1/applications/:app_id

Query Parameters

api_key
string

You can find your API key in your account overview

api_secret
string

You can find your API secret in your account overview

Path Parameters

app_id
string
Required

The ID allocated to your application by Nexmo.

Responses
Content Type
application/json

OK

id
string
exampleaaaaaaaa-bbbb-cccc-dddd-0123456789ab

The ID allocated to your application by Nexmo.

name
string
Required
exampleMy Application

The name of your application

voice
object
Required

The Nexmo product that you access with this application.

webhooks
array
endpoint_type
string
Required
exampleanswer_url
Must be one of:answer_urlevent_url
endpoint
string(url)
Required
examplehttps://example.com/webhooks/answer

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

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

Must be one of:GETPOST
messages
object
Required

The Nexmo product that you access with this application.

webhooks
array
endpoint_type
string
Required
examplestatus_url
Must be one of:inbound_urlstatus_url
endpoint
string(url)
Required
examplehttps://example.com/webhooks/status

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

http_method
string
Required
examplePOST

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

Must be one of:GETPOST
keys
object

The Nexmo product that you access with this application.

public_key
string
examplePUBLIC_KEY

The public key used to validate the JWT.

_links
object

A series of links between resources in this API in the following HAL specification.

href
string(url)
example/v1/applications/aaaaaaaa-bbbb-cccc-dddd-0123456789ab

The link URL.

Example Response

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

puthttps://api.nexmo.com/v1/applications/:app_id

Path Parameters

app_id
string
Required

The ID allocated to your application by Nexmo.

Request Body
Content Type
application/json

api_key
string
Required
exampleap1k3y

You can find your API key in your account overview

api_secret
string
Required
example230e6cf0709417176df1b4fc1e083adc

You can find your API secret in your account overview

name
string
Required
exampleUpdatedApplication

The name of your application.

type
string
Required
examplevoice

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:voicemessages
answer_url
string(url)
examplehttps://example.com/webhooks/answer

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

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

event_url
string(url)
examplehttps://example.com/webhooks/event

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

event_method
string
DefaultPOST
examplePOST

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

Example Request

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

Responses
Content Type
application/json

OK

id
string
exampleaaaaaaaa-bbbb-cccc-dddd-0123456789ab

The ID allocated to your application by Nexmo.

name
string
Required
exampleMy Application

The name of your application

voice
object
Required

The Nexmo product that you access with this application.

webhooks
array
endpoint_type
string
Required
exampleanswer_url
Must be one of:answer_urlevent_url
endpoint
string(url)
Required
examplehttps://example.com/webhooks/answer

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

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

Must be one of:GETPOST
messages
object
Required

The Nexmo product that you access with this application.

webhooks
array
endpoint_type
string
Required
examplestatus_url
Must be one of:inbound_urlstatus_url
endpoint
string(url)
Required
examplehttps://example.com/webhooks/status

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

http_method
string
Required
examplePOST

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

Must be one of:GETPOST
keys
object

The Nexmo product that you access with this application.

public_key
string
examplePUBLIC_KEY

The public key used to validate the JWT.

_links
object

A series of links between resources in this API in the following HAL specification.

href
string(url)
example/v1/applications/aaaaaaaa-bbbb-cccc-dddd-0123456789ab

The link URL.

Example Response

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

deletehttps://api.nexmo.com/v1/applications/:app_id

Path Parameters

app_id
string
Required

The ID allocated to your application by Nexmo.

Responses

No content