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:

cURL
PHP
Python
Ruby

#!/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

<?php

$base_url = 'https://api.nexmo.com' ;
$version = '/v1';
$action = '/applications/?';

//Create an Application for Voice API.
$url = $base_url . $version . $action . http_build_query([
    'api_key' =>  'API_KEY',
    'api_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
//

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, array("Accept: application/json", "Content-Length: 0" ));
curl_setopt($ch, CURLOPT_HEADER, 1);
$response = curl_exec($ch);

$header_size = curl_getinfo($ch, CURLINFO_HEADER_SIZE);
$header = substr($response, 0, $header_size);
$body = substr($response, $header_size);

if (strpos($header, '201')){
    $application = json_decode($body, true);
    if (! isset ($application['type'])){
        echo("Application " . $application['name']
                . " has an ID of:" . $application['id'] . "\n" ) ;
        echo("  Use the links to navigate. For example: "
            . $base_url
            . $application['_links']['self']['href'] . "\n"  );
    }else {
        echo ( "Error: " . $application['type']
            . " because of " . $application['error_title'] . "\n" );
    }
    foreach($application['voice']['webhooks'] as $webhook)
        echo ( "  " . $webhook['endpoint_type'] . " is " . $webhook['endpoint'] . "\n"  );

    echo("  Stock your public and private keys somewhere secure.\n" ) ;
    echo("  You use them to connect to Nexmo endpoints. They are:\n" ) ;
    echo("  " . $application['keys']['public_key'] );
    echo("  " . $application['keys']['private_key'] );
}
else {
    $error = json_decode($body, true);
    echo("Your request failed because:\n");
    echo("  " . $error['type'] . "  " . $error['error_title']   );
}

import requests

url = 'https://api.nexmo.com/v1/applications'
data = {
        'api_key': 'API_KEY',
        'api_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.

resp = requests.post(url, params=data)

try:
    if resp.status_code == 201:
        application = resp.json()
        print "Application " + application['name'] + " has an ID of: " + application['id']
        for webhook in application['voice']['webhooks']:
                print "  " + webhook['endpoint_type'] + " is " + webhook['endpoint']
        print "  You use your private key to connect to Nexmo endpoints:"
        print "  " + application['keys']['private_key']
    else:
        print "HTTP Response: " + resp.status_code
        print resp.json()

except requests.exceptions.HTTPError as e:
    print e

require 'nexmo'

nexmo_client = Nexmo::Client.new(api_key: 'API_KEY', api_secret: 'API_SECRET')

id = 'aaaaaaaa-bbbb-cccc-dddd-0123456789ab'

application = nexmo_client.applications.create(id, {
  name: 'Example Application',
  type: 'voice',
  answer_url: 'https://example.com/answer',
  event_url: 'https://example.com/event',
})

application.id
#=> "aaaaaaaa-bbbb-cccc-dddd-0123456789ab"

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`	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:

cURL
PHP
Python
Ruby

#!/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"

<?php

$base_url = 'https://api.nexmo.com' ;
$version = '/v1';
$action = '/applications/?';

$url = $base_url . $version . $action . http_build_query([
    'api_key' => 'API_KEY',
    'api_secret' => 'API_SECRET'
]);

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, array('Accept: application/json'));
curl_setopt($ch, CURLOPT_HEADER, 1);
$response = curl_exec($ch);

$header_size = curl_getinfo($ch, CURLINFO_HEADER_SIZE);
$header = substr($response, 0, $header_size);
$body = substr($response, $header_size);

if (strpos($header, '200')){
    $decoded_response = json_decode($body, true);
    echo("You have " . $decoded_response['count'] . " applications\n");
    echo("Page " . $decoded_response['page_index']
        . " lists " . $decoded_response['page_size'] . " applications\n");
    echo("Use the links to navigate. For example: "
        . $base_url .  $decoded_response['_links']['last']['href'] . "\n"  );
    $applications = $decoded_response['_embedded']['applications'] ;

    foreach ( $applications as $application ) {
        echo "  Application ID is:" . $application['id'] . "\n"  ;
        foreach($application['voice']['webhooks'] as $webhook)
            echo ( "    " . $webhook['endpoint_type'] . " is " . $webhook['endpoint'] . "\n"  );
    }
}
else {
    $error = json_decode($body, true);
    echo("Your request failed because:\n");
    echo("  " . $error['type'] . "  " . $error['error_title']   );
}

import requests

url = 'https://api.nexmo.com/v1/applications'
data = {
    'api_key': 'API_KEY',
    'api_secret': 'API_SECRET'
}

resp = requests.get(url, params=data)
try:
    if resp.status_code == 200:
        resp_data = resp.json()
        print "You have " + str(resp_data['count']) + " applications"
        print "Page " + str(resp_data['page_index']) + \
            " lists " + str(resp_data['page_size']) + " applications"
        print "Use the links to navigate. For example: https://api.nexmo.com" \
            +  resp_data['_links']['last']['href']
        for application in resp_data['_embedded']['applications'] :
            print "Application " + application['name'] + \
                " has an ID of: " + application['id']
            for webhook in application['voice']['webhooks'] :
                print "  " + webhook['endpoint_type'] + " is " + webhook['endpoint']
    else:
        print "Your request failed because:"
        print resp.json()
except requests.exceptions.HTTPError as e:
    print e

require 'nexmo'

nexmo_client = Nexmo::Client.new(api_key: 'API_KEY', api_secret: 'API_SECRET')

applications = nexmo_client.applications.list

applications.count
#=> 2

applications._embedded.applications[0].id
#=> "aaaaaaaa-bbbb-cccc-dddd-0123456789ab"

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 is 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:

cURL
PHP
Python
Ruby

#!/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"

<?php

$base_url = 'https://api.nexmo.com' ;
$version = '/v1';
$action = '/applications';
$app_id = '/APPLICATION_ID?';

$url = $base_url . $version . $action . $app_id . http_build_query([
    'api_key' => 'API_KEY',
    'api_secret' => 'API_SECRET'
]);

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, array('Accept: application/json'));
curl_setopt($ch, CURLOPT_HEADER, 1);
$response = curl_exec($ch);

$header_size = curl_getinfo($ch, CURLINFO_HEADER_SIZE);
$header = substr($response, 0, $header_size);
$body = substr($response, $header_size);

if (strpos($header, '200')){
    $application = json_decode($body, true);
    echo("Application " . $application['name'] . " has an ID of:" . $application['id'] . "\n" ) ;
    echo("  Use the links to navigate. For example: " . $base_url .  $application['_links']['self']['href'] . "\n"  );
    foreach($application['voice']['webhooks'] as $webhook)
        echo ( "  " . $webhook['endpoint_type'] . " is " . $webhook['endpoint'] . "\n"  );
}
else {
    $error = json_decode($body, true);
    echo("Your request failed because:\n");
    echo("  " . $error['type'] . "  " . $error['error_title']   );
}

import requests

url = 'https://api.nexmo.com/v1/applications/APPLICATION_ID'
data = {
    'api_key': 'API_KEY',
    'api_secret': 'API_SECRET'
}

resp = requests.get(url, params=data)

try:
    if resp.status_code == 200:
        application = resp.json()
        print "Application " + application['name'] + " has an ID of:" + application['id']
        for webhook in application['voice']['webhooks'] :
            print "  " + webhook['endpoint_type'] + " is " + webhook['endpoint']
    else:
        print "Your request failed because:"
        print resp.json()
except requests.exceptions.HTTPError as e:
    print e

require 'nexmo'

nexmo_client = Nexmo::Client.new(api_key: 'API_KEY', api_secret: 'API_SECRET')

application = nexmo_client.applications.get('aaaaaaaa-bbbb-cccc-dddd-0123456789ab')

application.id
#=> 'aaaaaaaa-bbbb-cccc-dddd-0123456789ab'

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:

cURL
PHP
Python
Ruby

#!/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"

<?php

$base_url = 'https://api.nexmo.com' ;
$version = '/v1';
$action = '/applications';
$app_id = '/APPLICATION_ID?';

$url = $base_url . $version . $action .  $app_id . http_build_query([
    'api_key' =>  'API_KEY',
    'api_secret' => 'API_SECRET',
    'name' => 'MyFirstApplication',
    'type' => 'voice',
    'answer_url' => 'https://example.com/ncco',
    'event_url' => 'https://example.com/call_status'
]);

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_PUT, 1);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, array('Accept: application/json'));
curl_setopt($ch, CURLOPT_HEADER, 1);
$response = curl_exec($ch);

$header_size = curl_getinfo($ch, CURLINFO_HEADER_SIZE);
$header = substr($response, 0, $header_size);
$body = substr($response, $header_size);

if (strpos($header, '200')){
    $application = json_decode($body, true);
    echo("Application " . $application['name'] . " has an ID of:" . $application['id'] . "\n" ) ;
    echo("  Use the links to navigate. For example: " . $base_url .  $application['_links']['self']['href'] . "\n"  );
    foreach($application['voice']['webhooks'] as $webhook)
        echo ( "  " . $webhook['endpoint_type'] . " is " . $webhook['endpoint'] . "\n"  );
    echo("  You use your private_key to connect to Nexmo endpoints:\n" ) ;
    echo("  " . $application['keys']['private_key'] );}
else {
    $error = json_decode($body, true);
    echo("Your request failed because:\n");
    echo("  " . $error['type'] . "  " . $error['error_title']   );
}

import requests

application_id = 'APPLICATION_ID'
url = 'https://api.nexmo.com/v1/applications/' + application_id

data = {
        'api_key': 'API_KEY',
        'api_secret': 'API_SECRET',
        'name' : 'MyFirstApplication',
        'type' : 'voice',
        'answer_url' : 'https://example.com/ncco',
        'event_url' : 'https://example.com/call_status'
}

resp = requests.put(url, params=data)
try:
    if resp.status_code == 200:
        application = resp.json()
        print "Application " + application['name'] + " has an ID of:" + application['id']
        for webhook in application['voice']['webhooks']:
                print "  " + webhook['endpoint_type'] + " is " + webhook['endpoint']
    else:
        print "Your request failed because:"
        print resp.json()

except requests.exceptions.HTTPError as e:
    print e

require 'nexmo'

nexmo_client = Nexmo::Client.new(api_key: 'API_KEY', api_secret: 'API_SECRET')

id = 'aaaaaaaa-bbbb-cccc-dddd-0123456789ab'

application = nexmo_client.applications.update(id, {
  name: 'MyFirstApplication',
  type: 'voice',
  answer_url: 'https://example.com/ncco',
  event_url: 'https://example.com/status',
})

application.id
#=> "aaaaaaaa-bbbb-cccc-dddd-0123456789ab"

Parameters

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

Parameter	Description	Required
`name`	The name of your application.	Yes
`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:

cURL
PHP
Python
Ruby

#!/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"

<?php

$base_url = 'https://api.nexmo.com' ;
$version = '/v1';
$action = '/applications';

$url = $base_url . $version . $action . "/APPLICATION_ID?" . http_build_query([
    'api_key' => ‘'API_KEY'’,
    'api_secret' => ‘'API_SECRET'’
]);

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "DELETE");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, array('Accept: application/json'));
curl_setopt($ch, CURLOPT_HEADER, 1);
$response = curl_exec($ch);

$header_size = curl_getinfo($ch, CURLINFO_HEADER_SIZE);
$header = substr($response, 0, $header_size);
$body = substr($response, $header_size);

if (strpos($header, '100')){
    echo("APPLICATION_ID deleted");

}
else {
    $error = json_decode($body, true);
    echo("Your request failed because:\n");
    echo("  " . $error['type'] . "  " . $error['error_title']   );
}

import requests

url = 'https://api.nexmo.com/v1/applications/APPLICATION_ID'
data = {
    'api_key': 'API_KEY',
    'api_secret': 'API_SECRET',
}

resp = requests.delete(url, params=data)
if resp.status_code == 204:
    print "Your applicaiton was deleted"
else :
    print "Your request failed because:"
    print resp.json()

require 'nexmo'

nexmo_client = Nexmo::Client.new(api_key: 'API_KEY', api_secret: 'API_SECRET')

nexmo_client.applications.delete('aaaaaaaa-bbbb-cccc-dddd-0123456789ab')

Response

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