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

Voice

#!/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 voice application:

Parameter Description Required
name The name of your application.
type The Nexmo product or products that you access with this application. Currently only voice and messages are supported.
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. The default value is GET. x
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. The default value is POST. x


Messages and Dispatch

#!/bin/bash

# Create an Application for Messages & Dispatch API

  base_url='https://api.nexmo.com'
  version='/v1'
  action='/applications/?'
  key='API_KEY'
  secret='API_SECRET'
  name='MyFirstApplication'
  type='messages'
  status_url='https://example.com/status'
  inbound_url='https://example.com/inbound'

  curl $base_url$version$action \
    -d api_key=$key \
    -d api_secret=$secret \
    -d name=$name \
    -d type=$type \
    -d status_url=$status_url \
    -d inbound_url=$inbound_url
<?php

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

# Create an Application for Messages & Dispatch API
$url = $base_url . $version . $action . http_build_query([
    'api_key' =>  'API_KEY',
    'api_secret' => 'API_SECRET',
    'name' => 'MyFirstApplication',
    'type' => 'messages',
    'status_url' => 'https://example.com/status',
    'inbound_url' => 'https://example.com/inbound'
]);



$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',
        'status_url' : 'https://example.com/status',
        'inbound_url' : 'https://example.com/inbound'
}

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: 'messages',
  status_url: 'https://example.com/status',
  inbound_url: 'https://example.com/inbound',
})

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

Parameters

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

Parameter Description Required
name The name of your application.
type The Nexmo product or products that you access with this application. Currently only voice and messages are supported.
status_url Nexmo sends Submitted, Delivered, Read and Rejected statuses for every message to this URL.
inbound_url Nexmo sends Inbound Messages to this URL.


Response

The JSON object for a 201 Created response looks like:

Voice

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

Messages and Dispatch

{
  "id": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
  "name": "My Application",
  "messages": {
    "webhooks": [
      {
        "endpoint_type": "status_url",
        "endpoint": "https://example.com/status"
      },
      {
        "endpoint_type": "inbound_url",
        "endpoint": "https://example.com/inbound"
      }
    ]
  },
  "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 Voice Messages
name The name of your application
type The Nexmo product or products that you access with this application. Currently only voice and messages are 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. x
answer_method The HTTP method used to make the request to answer_url. x
event_url Nexmo sends event information asynchronously to this URL when status changes. x
event_method The HTTP method used to send event information to event_url. x
status_url Nexmo sends Submitted, Delivered, Read and Rejected statuses for every message to this URL. x
inbound_url Nexmo sends Inbound Messages to this URL. x
_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"
<?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"
          }
        }
      },
      {
        "id": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
        "name": "My Application",
        "voice": {
          "messages": [
            {
              "endpoint_type": "status_url",
              "endpoint": "https://example.com/status"
            },
            {
              "endpoint_type": "inbound_url",
              "endpoint": "https://example.com/inbound"
            }
          ]
        },
        "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:

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

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 and messages are 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:

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

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 and messages are 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 and messages are 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:

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 application was deleted"
else :
    print "Your request failed because:"
    print resp.json()

Response

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