Nexmo provides an Application API to allow management of your Nexmo Applications.
This API is backwards compatible with version 1. Applications created using version 1 of the API can also be managed using version 2 (this version) of the API.
GET
https://api.nexmo.com/v2/applications
Host
https://api.nexmo.com
GET
/v2/applications
| Key | Description | Example | Default |
|---|---|---|---|
| Authorization |
Base64 encoded API key and secret joined by a colon. Read more |
Basic <base64> |
None |
The number of applications per page
The current page number (starts at 1)
The number of applications per page
The current page number (starts at 1)
The total number of applications
The total number of pages returned
A list of applications matching your existing filters
The application's ID
Friendly identifier for your application. This is not unique
Configuration for the products available in this application
Voice related configuration
The URL that Nexmo requests when a call is placed/received. Must return an NCCO
The HTTP method used to fetch your NCCO from your answer_url
If your answer_url is offline or returns a HTTP error code, Nexmo will make a request to a
fallback_answer_url if it is set. This URL must return an NCCO.
The HTTP method used to fetch your NCCO from your answer_url
The URL that Nexmo sends events related to your call to
The HTTP method used to send events to your server
Messages / Dispatch related configuration
The URL that Nexmo forwards inbound messages to on your server
The HTTP method used to send inbound messages to your server
The URL that Nexmo sends events related to your messages to
The HTTP method used to send events to your server (always POST)
RTC / Conversation Service related configuration
Specify the vbc capability to enable zero-rated calls for VBC number programmability service applications. This is always an empty object.
{
"page_size": 10,
"page": 1,
"total_items": 6,
"total_pages": 1,
"_embedded": {
"applications": [
{
"id": "78d335fa323d01149c3dd6f0d48968cf",
"name": "My Application",
"capabilities": {
"voice": {
"webhooks": {
"answer_url": {
"address": "https://example.com/webhooks/answer",
"http_method": "POST"
},
"fallback_answer_url": {
"address": "https://fallback.example.com/webhooks/answer",
"http_method": "POST"
},
"event_url": {
"address": "https://example.com/webhooks/event",
"http_method": "POST"
}
}
},
"messages": {
"webhooks": {
"inbound_url": {
"address": "https://example.com/webhooks/inbound",
"http_method": "POST"
},
"status_url": {
"address": "https://example.com/webhooks/status",
"http_method": "POST"
}
}
},
"rtc": {
"webhooks": {
"event_url": {
"address": "https://example.com/webhooks/event",
"http_method": "POST"
}
}
},
"vbc": {}
}
}
]
}
}{
"type": "https://developer.nexmo.com/api-errors/application#list-validation",
"title": "Bad Request",
"detail": "The request failed due to validation errors",
"invalid_parameters": [
{
"name": "page_size",
"reason": "must be between 1 and 100"
}
],
"instance": "797a8f199c45014ab7b08bfe9cc1c12c"
}{
"type": "https://developer.nexmo.com/api-errors#unauthorized",
"title": "Invalid credentials supplied",
"detail": "You did not provide correct credentials.",
"instance": "797a8f199c45014ab7b08bfe9cc1c12c"
}{
"type": "https://developer.nexmo.com/api-errors#wrong-verb",
"title": "Request method not allowed",
"detail": "Request method 'TRACE' not supported",
"instance": "797a8f199c45014ab7b08bfe9cc1c12c"
}{
"type": "https://developer.nexmo.com/api-errors#accept-header",
"title": "Invalid Accept header",
"detail": "Invalid Accept header provided. Must be one of the following: 'application/json'",
"instance": "797a8f199c45014ab7b08bfe9cc1c12c"
}POST
https://api.nexmo.com/v2/applications
Host
https://api.nexmo.com
POST
/v2/applications
| Key | Description | Example | Default |
|---|---|---|---|
| Authorization |
Base64 encoded API key and secret joined by a colon. Read more |
Basic <base64> |
None |
Application Name
Public key
Your application can use multiple products. This contains the configuration for each product. This replaces the application type from version 1 of the Application API.
Voice application webhook config
Voice application webhook config
The URL that Nexmo make a request to when a call is placed/received. Must return an NCCO
The URL that Nexmo make a request to when a call is placed/received. Must return an NCCO
The URL that Nexmo make a request to when a call is placed/received. Must return an NCCO
Must be one of:GET or POST
If your answer_url is offline or returns a HTTP error code, Nexmo will make a request to a
fallback_answer_url if it is set. This URL must return an NCCO.
If your answer_url is offline or returns a HTTP error code, Nexmo will make a request to a
fallback_answer_url if it is set. This URL must return an NCCO.
If your answer_url is offline or returns a HTTP error code, Nexmo will make a request to a
fallback_answer_url if it is set. This URL must return an NCCO.
GET or POST
Nexmo will send call events (e.g. ringing, answered) to this URL
Nexmo will send call events (e.g. ringing, answered) to this URL
Nexmo will send call events (e.g. ringing, answered) to this URL
GET or POST
RTC / Client SDK application webhook config
RTC / Client SDK application webhook config
Nexmo will send RTC events to this URL
Nexmo will send RTC events to this URL
Nexmo will send RTC events to this URL
Must be one of:GET or POST
Messages and Dispatch application webhook config
Messages and Dispatch application webhook config
Nexmo will forward inbound messages to this URL
Nexmo will forward inbound messages to this URL
Nexmo will forward inbound messages to this URL
Must be one of:POST
Nexmo will send message status updates (e.g. delivered, seen) to this URL
Nexmo will send message status updates (e.g. delivered, seen) to this URL
Nexmo will send message status updates (e.g. delivered, seen) to this URL
POST
Specify vbc capability to enable zero-rated calls for VBC number programmability service applications. This must be an empty object.
The application's ID
Friendly identifier for your application. This is not unique
Configuration for the products available in this application
Voice related configuration
The URL that Nexmo requests when a call is placed/received. Must return an NCCO
The HTTP method used to fetch your NCCO from your answer_url
If your answer_url is offline or returns a HTTP error code, Nexmo will make a request to a
fallback_answer_url if it is set. This URL must return an NCCO.
The HTTP method used to fetch your NCCO from your answer_url
The URL that Nexmo sends events related to your call to
The HTTP method used to send events to your server
Messages / Dispatch related configuration
The URL that Nexmo forwards inbound messages to on your server
The HTTP method used to send inbound messages to your server
The URL that Nexmo sends events related to your messages to
The HTTP method used to send events to your server (always POST)
RTC / Conversation Service related configuration
Specify the vbc capability to enable zero-rated calls for VBC number programmability service applications. This is always an empty object.
{
"name": "Demo Application"
}{
"name": "Demo Application",
"keys": {
"public_key": "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCA\nKOxjsU4pf/sMFi9N0jqcSLcjxu33G\nd/vynKnlw9SENi+UZR44GdjGdmfm1\ntL1eA7IBh2HNnkYXnAwYzKJoa4eO3\n0kYWekeIZawIwe/g9faFgkev+1xsO\nOUNhPx2LhuLmgwWSRS4L5W851Xe3f\nUQIDAQAB\n-----END PUBLIC KEY-----\n"
},
"capabilities": {
"voice": {
"webhooks": {
"answer_url": {
"address": "https://example.com/webhooks/answer",
"http_method": "GET"
},
"fallback_answer_url": {
"address": "https://fallback.example.com/webhooks/answer",
"http_method": "GET"
},
"event_url": {
"address": "https://example.com/webhooks/event",
"http_method": "POST"
}
}
},
"rtc": {
"webhooks": {
"event_url": {
"address": "https://example.com/webhooks/event",
"http_method": "POST"
}
}
},
"messages": {
"webhooks": {
"inbound_url": {
"address": "https://example.com/webhooks/inbound",
"http_method": "POST"
},
"status_url": {
"address": "https://example.com/webhooks/status",
"http_method": "POST"
}
}
}
}
}{
"id": "78d335fa323d01149c3dd6f0d48968cf",
"name": "My Application",
"capabilities": {
"voice": {
"webhooks": {
"answer_url": {
"address": "https://example.com/webhooks/answer",
"http_method": "POST"
},
"fallback_answer_url": {
"address": "https://fallback.example.com/webhooks/answer",
"http_method": "POST"
},
"event_url": {
"address": "https://example.com/webhooks/event",
"http_method": "POST"
}
}
},
"messages": {
"webhooks": {
"inbound_url": {
"address": "https://example.com/webhooks/inbound",
"http_method": "POST"
},
"status_url": {
"address": "https://example.com/webhooks/status",
"http_method": "POST"
}
}
},
"rtc": {
"webhooks": {
"event_url": {
"address": "https://example.com/webhooks/event",
"http_method": "POST"
}
}
},
"vbc": {}
},
"keys": {
"public_key": "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCA\nKOxjsU4pf/sMFi9N0jqcSLcjxu33G\nd/vynKnlw9SENi+UZR44GdjGdmfm1\ntL1eA7IBh2HNnkYXnAwYzKJoa4eO3\n0kYWekeIZawIwe/g9faFgkev+1xsO\nOUNhPx2LhuLmgwWSRS4L5W851Xe3f\nUQIDAQAB\n-----END PUBLIC KEY-----\n",
"private_key": "-----BEGIN PRIVATE KEY-----\nMIIEvQIBADANBgkqhkiG9w0BAQEFA\nASCBKcwggSjAgEAAoIBAQDEPpvi+3\nRH1efQ\\nkveWzZDrNNoEXmBw61w+O\n0u/N36tJnN5XnYecU64yHzu2ByEr0\n7iIvYbavFnADwl\\nHMTJwqDQakpa3\n8/SFRnTDq3zronvNZ6nOp7S6K7pcZ\nrw/CvrL6hXT1x7cGBZ4jPx\\nqhjqY\nuJPgZD7OVB69oYOV92vIIJ7JLYwqb\n-----END PRIVATE KEY-----\n"
}
}{
"type": "https://developer.nexmo.com/api-errors/application#payload-validation",
"title": "Bad Request",
"detail": "The request failed due to validation errors",
"invalid_parameters": [
{
"name": "capabilities.voice.webhooks.answer_url.http_method",
"reason": "must be one of: GET, POST"
}
],
"instance": "797a8f199c45014ab7b08bfe9cc1c12c"
}{
"type": "https://developer.nexmo.com/api-errors#unauthorized",
"title": "Invalid credentials supplied",
"detail": "You did not provide correct credentials.",
"instance": "797a8f199c45014ab7b08bfe9cc1c12c"
}{
"type": "https://developer.nexmo.com/api-errors#wrong-verb",
"title": "Request method not allowed",
"detail": "Request method 'TRACE' not supported",
"instance": "797a8f199c45014ab7b08bfe9cc1c12c"
}{
"type": "https://developer.nexmo.com/api-errors#accept-header",
"title": "Invalid Accept header",
"detail": "Invalid Accept header provided. Must be one of the following: 'application/json'",
"instance": "797a8f199c45014ab7b08bfe9cc1c12c"
}{
"type": "https://developer.nexmo.com/api-errors#content-type-header",
"title": "Unsupported Content-Type header",
"detail": "Unsupported Content-Type header provided. Must be one of the following: 'application/json'",
"instance": "797a8f199c45014ab7b08bfe9cc1c12c"
}GET
https://api.nexmo.com/v2/applications/:id
Host
https://api.nexmo.com
GET
/v2/applications/:id
| Key | Description | Example | Default |
|---|---|---|---|
| Authorization |
Base64 encoded API key and secret joined by a colon. Read more |
Basic <base64> |
None |
The ID of the application
The application's ID
Friendly identifier for your application. This is not unique
Configuration for the products available in this application
Voice related configuration
The URL that Nexmo requests when a call is placed/received. Must return an NCCO
The HTTP method used to fetch your NCCO from your answer_url
If your answer_url is offline or returns a HTTP error code, Nexmo will make a request to a
fallback_answer_url if it is set. This URL must return an NCCO.
The HTTP method used to fetch your NCCO from your answer_url
The URL that Nexmo sends events related to your call to
The HTTP method used to send events to your server
Messages / Dispatch related configuration
The URL that Nexmo forwards inbound messages to on your server
The HTTP method used to send inbound messages to your server
The URL that Nexmo sends events related to your messages to
The HTTP method used to send events to your server (always POST)
RTC / Conversation Service related configuration
Specify the vbc capability to enable zero-rated calls for VBC number programmability service applications. This is always an empty object.
{
"id": "78d335fa323d01149c3dd6f0d48968cf",
"name": "My Application",
"capabilities": {
"voice": {
"webhooks": {
"answer_url": {
"address": "https://example.com/webhooks/answer",
"http_method": "POST"
},
"fallback_answer_url": {
"address": "https://fallback.example.com/webhooks/answer",
"http_method": "POST"
},
"event_url": {
"address": "https://example.com/webhooks/event",
"http_method": "POST"
}
}
},
"messages": {
"webhooks": {
"inbound_url": {
"address": "https://example.com/webhooks/inbound",
"http_method": "POST"
},
"status_url": {
"address": "https://example.com/webhooks/status",
"http_method": "POST"
}
}
},
"rtc": {
"webhooks": {
"event_url": {
"address": "https://example.com/webhooks/event",
"http_method": "POST"
}
}
},
"vbc": {}
}
}{
"type": "https://developer.nexmo.com/api-errors#unauthorized",
"title": "Invalid credentials supplied",
"detail": "You did not provide correct credentials.",
"instance": "797a8f199c45014ab7b08bfe9cc1c12c"
}{
"type": "https://developer.nexmo.com/api-errors#not-found",
"title": "Not Found",
"detail": "ID 'ABC123' does not exist, or you do not have access",
"instance": "797a8f199c45014ab7b08bfe9cc1c12c"
}{
"type": "https://developer.nexmo.com/api-errors#wrong-verb",
"title": "Request method not allowed",
"detail": "Request method 'TRACE' not supported",
"instance": "797a8f199c45014ab7b08bfe9cc1c12c"
}{
"type": "https://developer.nexmo.com/api-errors#accept-header",
"title": "Invalid Accept header",
"detail": "Invalid Accept header provided. Must be one of the following: 'application/json'",
"instance": "797a8f199c45014ab7b08bfe9cc1c12c"
}PUT
https://api.nexmo.com/v2/applications/:id
Host
https://api.nexmo.com
PUT
/v2/applications/:id
| Key | Description | Example | Default |
|---|---|---|---|
| Authorization |
Base64 encoded API key and secret joined by a colon. Read more |
Basic <base64> |
None |
The ID of the application
Application Name
Public key
Your application can use multiple products. This contains the configuration for each product. This replaces the application type from version 1 of the Application API.
Voice application webhook config
Voice application webhook config
The URL that Nexmo make a request to when a call is placed/received. Must return an NCCO
The URL that Nexmo make a request to when a call is placed/received. Must return an NCCO
The URL that Nexmo make a request to when a call is placed/received. Must return an NCCO
Must be one of:GET or POST
If your answer_url is offline or returns a HTTP error code, Nexmo will make a request to a
fallback_answer_url if it is set. This URL must return an NCCO
If your answer_url is offline or returns a HTTP error code, Nexmo will make a request to a
fallback_answer_url if it is set. This URL must return an NCCO
If your answer_url is offline or returns a HTTP error code, Nexmo will make a request to a
fallback_answer_url if it is set. This URL must return an NCCO
GET or POST
Nexmo will send call events (e.g. ringing, answered) to this URL
Nexmo will send call events (e.g. ringing, answered) to this URL
Nexmo will send call events (e.g. ringing, answered) to this URL
GET or POST
RTC / Client SDK application webhook config
RTC / Client SDK application webhook config
Nexmo will send RTC events to this URL
Nexmo will send RTC events to this URL
Nexmo will send RTC events to this URL
Must be one of:GET or POST
Messages and Dispatch application webhook config
Messages and Dispatch application webhook config
Nexmo will forward inbound messages to this URL
Nexmo will forward inbound messages to this URL
Nexmo will forward inbound messages to this URL
Must be one of:POST
Nexmo will send message status updates (e.g. delivered, seen) to this URL
Nexmo will send message status updates (e.g. delivered, seen) to this URL
Nexmo will send message status updates (e.g. delivered, seen) to this URL
POST
Specify the vbc capability to enable zero-rated calls for VBC number programmability service applications. This must be an empty object.
The application's ID
Friendly identifier for your application. This is not unique
Configuration for the products available in this application
Voice related configuration
The URL that Nexmo requests when a call is placed/received. Must return an NCCO
The HTTP method used to fetch your NCCO from your answer_url
If your answer_url is offline or returns a HTTP error code, Nexmo will make a request to a
fallback_answer_url if it is set. This URL must return an NCCO.
The HTTP method used to fetch your NCCO from your answer_url
The URL that Nexmo sends events related to your call to
The HTTP method used to send events to your server
Messages / Dispatch related configuration
The URL that Nexmo forwards inbound messages to on your server
The HTTP method used to send inbound messages to your server
The URL that Nexmo sends events related to your messages to
The HTTP method used to send events to your server (always POST)
RTC / Conversation Service related configuration
Specify the vbc capability to enable zero-rated calls for VBC number programmability service applications. This is always an empty object.
{
"name": "Demo Application"
}{
"name": "Demo Application",
"keys": {
"public_key": "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCA\nKOxjsU4pf/sMFi9N0jqcSLcjxu33G\nd/vynKnlw9SENi+UZR44GdjGdmfm1\ntL1eA7IBh2HNnkYXnAwYzKJoa4eO3\n0kYWekeIZawIwe/g9faFgkev+1xsO\nOUNhPx2LhuLmgwWSRS4L5W851Xe3f\nUQIDAQAB\n-----END PUBLIC KEY-----\n"
},
"capabilities": {
"voice": {
"webhooks": {
"answer_url": {
"address": "https://example.com/webhooks/answer",
"http_method": "GET"
},
"fallback_answer_url": {
"address": "https://fallback.example.com/webhooks/answer",
"http_method": "GET"
},
"event_url": {
"address": "https://example.com/webhooks/event",
"http_method": "POST"
}
}
},
"rtc": {
"webhooks": {
"event_url": {
"address": "https://example.com/webhooks/event",
"http_method": "POST"
}
}
},
"messages": {
"webhooks": {
"inbound_url": {
"address": "https://example.com/webhooks/inbound",
"http_method": "POST"
},
"status_url": {
"address": "https://example.com/webhooks/status",
"http_method": "POST"
}
}
}
}
}{
"id": "78d335fa323d01149c3dd6f0d48968cf",
"name": "My Application",
"capabilities": {
"voice": {
"webhooks": {
"answer_url": {
"address": "https://example.com/webhooks/answer",
"http_method": "POST"
},
"fallback_answer_url": {
"address": "https://fallback.example.com/webhooks/answer",
"http_method": "POST"
},
"event_url": {
"address": "https://example.com/webhooks/event",
"http_method": "POST"
}
}
},
"messages": {
"webhooks": {
"inbound_url": {
"address": "https://example.com/webhooks/inbound",
"http_method": "POST"
},
"status_url": {
"address": "https://example.com/webhooks/status",
"http_method": "POST"
}
}
},
"rtc": {
"webhooks": {
"event_url": {
"address": "https://example.com/webhooks/event",
"http_method": "POST"
}
}
},
"vbc": {}
},
"keys": {
"public_key": "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCA\nKOxjsU4pf/sMFi9N0jqcSLcjxu33G\nd/vynKnlw9SENi+UZR44GdjGdmfm1\ntL1eA7IBh2HNnkYXnAwYzKJoa4eO3\n0kYWekeIZawIwe/g9faFgkev+1xsO\nOUNhPx2LhuLmgwWSRS4L5W851Xe3f\nUQIDAQAB\n-----END PUBLIC KEY-----\n",
"private_key": "-----BEGIN PRIVATE KEY-----\nMIIEvQIBADANBgkqhkiG9w0BAQEFA\nASCBKcwggSjAgEAAoIBAQDEPpvi+3\nRH1efQ\\nkveWzZDrNNoEXmBw61w+O\n0u/N36tJnN5XnYecU64yHzu2ByEr0\n7iIvYbavFnADwl\\nHMTJwqDQakpa3\n8/SFRnTDq3zronvNZ6nOp7S6K7pcZ\nrw/CvrL6hXT1x7cGBZ4jPx\\nqhjqY\nuJPgZD7OVB69oYOV92vIIJ7JLYwqb\n-----END PRIVATE KEY-----\n"
}
}{
"type": "https://developer.nexmo.com/api-errors/application#payload-validation",
"title": "Bad Request",
"detail": "The request failed due to validation errors",
"invalid_parameters": [
{
"name": "capabilities.voice.webhooks.answer_url.http_method",
"reason": "must be one of: GET, POST"
}
],
"instance": "797a8f199c45014ab7b08bfe9cc1c12c"
}{
"type": "https://developer.nexmo.com/api-errors#unauthorized",
"title": "Invalid credentials supplied",
"detail": "You did not provide correct credentials.",
"instance": "797a8f199c45014ab7b08bfe9cc1c12c"
}{
"type": "https://developer.nexmo.com/api-errors#not-found",
"title": "Not Found",
"detail": "ID 'ABC123' does not exist, or you do not have access",
"instance": "797a8f199c45014ab7b08bfe9cc1c12c"
}{
"type": "https://developer.nexmo.com/api-errors#wrong-verb",
"title": "Request method not allowed",
"detail": "Request method 'TRACE' not supported",
"instance": "797a8f199c45014ab7b08bfe9cc1c12c"
}{
"type": "https://developer.nexmo.com/api-errors#accept-header",
"title": "Invalid Accept header",
"detail": "Invalid Accept header provided. Must be one of the following: 'application/json'",
"instance": "797a8f199c45014ab7b08bfe9cc1c12c"
}{
"type": "https://developer.nexmo.com/api-errors#content-type-header",
"title": "Unsupported Content-Type header",
"detail": "Unsupported Content-Type header provided. Must be one of the following: 'application/json'",
"instance": "797a8f199c45014ab7b08bfe9cc1c12c"
}Deleting an application cannot be undone.
DELETE
https://api.nexmo.com/v2/applications/:id
Host
https://api.nexmo.com
DELETE
/v2/applications/:id
| Key | Description | Example | Default |
|---|---|---|---|
| Authorization |
Base64 encoded API key and secret joined by a colon. Read more |
Basic <base64> |
None |
The ID of the application
Success{
"type": "https://developer.nexmo.com/api-errors#unauthorized",
"title": "Invalid credentials supplied",
"detail": "You did not provide correct credentials.",
"instance": "797a8f199c45014ab7b08bfe9cc1c12c"
}{
"type": "https://developer.nexmo.com/api-errors#not-found",
"title": "Not Found",
"detail": "ID 'ABC123' does not exist, or you do not have access",
"instance": "797a8f199c45014ab7b08bfe9cc1c12c"
}{
"type": "https://developer.nexmo.com/api-errors#wrong-verb",
"title": "Request method not allowed",
"detail": "Request method 'TRACE' not supported",
"instance": "797a8f199c45014ab7b08bfe9cc1c12c"
}{
"type": "https://developer.nexmo.com/api-errors#accept-header",
"title": "Invalid Accept header",
"detail": "Invalid Accept header provided. Must be one of the following: 'application/json'",
"instance": "797a8f199c45014ab7b08bfe9cc1c12c"
}The following is a non-exhaustive list of error codes that may occur while using this API. These codes are in addition to any of our generic error codes.
| Code | Details |
|---|---|
| payload-validation | Invalid request. See |
| list-validation | Invalid request. See |
| rate-limit | The request was rate limited |