{ "openapi": "3.0.0", "info": { "title": "Nexmo Application API", "x-metaTitle": "Vonage Application API (v1.0) Reference | Vonage API Documentation", "x-metaDescription": "Find quick answers to questions about the Vonage Application API (v1.0) in this reference guide. Learn more in Vonage's API documentation.", "version": "1.0.2", "description": "A Nexmo application contains the security and configuration information you need to connect to Nexmo endpoints and easily use our products.", "x-note": { "type": "alert", "icon": "warning-line", "header": "Applications V1 is deprecated", "description": "This version of the API has been deprecated. Please use [version 2](/api/application.v2) going forwards." }, "contact": { "name": "Nexmo.com", "email": "devrel@nexmo.com", "url": "https://developer.nexmo.com/", "x-twitter": "Nexmo" }, "termsOfService": "https://www.nexmo.com/terms-of-use", "license": { "name": "The MIT License (MIT)", "url": "https://opensource.org/licenses/MIT" }, "x-logo": { "url": "https://twitter.com/Nexmo/profile_image?size=original" }, "x-apiClientRegistration": "${CUSTOMER_DASHBOARD_URL}/sign-up" }, "servers": [ { "url": "https://api.nexmo.com/v1/applications" } ], "externalDocs": { "url": "https://developer.nexmo.com/api/developer/application", "x-sha1": "d8836c374e2a7504bd2cd59e05fcee440f67cb44" }, "paths": { "/": { "get": { "summary": "Retrieve all Applications", "description": "You use a `GET` request to retrieve details of all applications associated with your account.", "operationId": "retrieveApplications", "parameters": [ { "$ref": "#/components/parameters/apiKeyQueryString" }, { "$ref": "#/components/parameters/apiSecretQueryString" }, { "name": "page_size", "required": false, "in": "query", "description": "Set the number of items returned on each call to this endpoint. The default is 10 records.", "schema": { "type": "integer", "default": 10 }, "example": 10 }, { "name": "page_index", "required": false, "in": "query", "description": "Set the offset from the first page. The default value is `0`.", "schema": { "type": "integer", "default": 0 }, "example": 0 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/applications" } } } } } }, "post": { "summary": "Create Application", "description": "You use a `POST` request to create a new application.", "operationId": "createApplication", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "api_key", "api_secret", "name", "type" ], "properties": { "api_key": { "$ref": "#/components/schemas/apiKey" }, "api_secret": { "$ref": "#/components/schemas/apiSecret" }, "name": { "description": "The name of your application.", "type": "string", "example": "My Application" }, "type": { "description": "The Nexmo product or products that you access with this application. Currently `voice` and `messages` application types are supported.", "type": "string", "example": "voice", "enum": [ "voice", "messages" ] }, "answer_url": { "description": "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.", "type": "string", "example": "https://example.com/webhooks/answer" }, "answer_method": { "description": "The HTTP method used to make the request to `answer_url`. The default value is `GET`.", "type": "string", "example": "GET" }, "event_url": { "description": "Nexmo sends event information asynchronously to this URL when status changes for `voice` applications. Always required for `voice` applications.", "type": "string", "example": "https://example.com/webhooks/event" }, "event_method": { "description": "The HTTP method used to send event information to `event_url`. The default value is `POST`. For `voice` type applications only.", "type": "string", "example": "POST" }, "status_url": { "description": "Nexmo sends event information asynchronously to this URL when status changes. Required for `messages` type applications only.", "type": "string", "example": "https://example.com/webhooks/status" }, "status_method": { "description": "The HTTP method used to send event information to `status_url`. The default value is `POST`. For `messages` type applications only.", "type": "string", "example": "POST" }, "inbound_url": { "description": "Nexmo sends a request to this URL when an inbound message is received. Required for `messages` type applications only.", "type": "string", "example": "https://example.com/webhooks/inbound" }, "inbound_method": { "description": "The HTTP method used to send event information to `inbound_url`. The default value is `POST`. For `messages` type applications only.", "type": "string", "example": "POST" } } } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/applicationCreated" } } } } } } }, "/{app_id}": { "get": { "summary": "Retrieve Application", "description": "You use a `GET` request to retrieve details about a single application.", "operationId": "retrieveApplication", "parameters": [ { "$ref": "#/components/parameters/apiKeyQueryString" }, { "$ref": "#/components/parameters/apiSecretQueryString" }, { "$ref": "#/components/parameters/app_id" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/application" } } } } } }, "put": { "summary": "Update Application", "description": "You use a `PUT` request to update an existing application.", "operationId": "updateApplication", "parameters": [ { "$ref": "#/components/parameters/app_id" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "api_key", "api_secret", "name", "type" ], "properties": { "api_key": { "$ref": "#/components/schemas/apiKey" }, "api_secret": { "$ref": "#/components/schemas/apiSecret" }, "name": { "description": "The name of your application.", "type": "string", "example": "UpdatedApplication" }, "type": { "description": "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.", "type": "string", "enum": [ "voice", "messages" ], "example": "voice" }, "answer_url": { "description": "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`.", "type": "string", "format": "url", "example": "https://example.com/webhooks/answer" }, "answer_method": { "description": "The HTTP method used to make the request to `answer_url`. The default value is `GET`.", "type": "string", "default": "GET", "example": "GET" }, "event_url": { "description": "Nexmo sends event information asynchronously to this URL when status changes.", "type": "string", "format": "url", "example": "https://example.com/webhooks/event" }, "event_method": { "description": "The HTTP method used to send event information to `event_url`. The default value is POST.", "type": "string", "default": "POST", "example": "POST" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/application" } } } } } }, "delete": { "summary": "Destroy Application", "description": "You use a `DELETE` request to delete a single application.", "operationId": "deleteApplication", "parameters": [ { "$ref": "#/components/parameters/app_id" } ], "responses": { "204": { "description": "No content" } } } } }, "components": { "parameters": { "app_id": { "name": "app_id", "in": "path", "required": true, "description": "The ID allocated to your application by Nexmo.", "schema": { "type": "string" }, "example": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab" }, "apiKeyQueryString": { "schema": { "type": "string" }, "name": "api_key", "in": "query", "required": true, "description": "You can find your API key in your [account overview](${CUSTOMER_DASHBOARD_URL}/account-overview)" }, "apiSecretQueryString": { "schema": { "type": "string" }, "name": "api_secret", "in": "query", "required": true, "description": "You can find your API secret in your [account overview](${CUSTOMER_DASHBOARD_URL}/account-overview)" } }, "schemas": { "apiKey": { "type": "string", "description": "You can find your API key in your [account overview](${CUSTOMER_DASHBOARD_URL}/account-overview)", "example": "ap1k3y" }, "apiSecret": { "type": "string", "description": "You can find your API secret in your [account overview](${CUSTOMER_DASHBOARD_URL}/account-overview)", "example": "230e6cf0709417176df1b4fc1e083adc" }, "links": { "type": "object", "description": "A series of links between resources in this API in the following [HAL specification](http://stateless.co/hal_specification.html).", "properties": { "href": { "type": "string", "format": "url", "description": "The link URL.", "example": "/v1/applications/aaaaaaaa-bbbb-cccc-dddd-0123456789ab" } } }, "voice": { "description": "The Nexmo product that you access with this application.", "type": "object", "properties": { "webhooks": { "type": "array", "items": { "type": "object", "required": [ "endpoint_type", "endpoint", "http_method" ], "properties": { "endpoint_type": { "type": "string", "enum": [ "answer_url", "event_url" ], "example": "answer_url" }, "endpoint": { "type": "string", "description": "`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.", "format": "url", "example": "https://example.com/webhooks/answer" }, "http_method": { "type": "string", "description": "The HTTP method used to send event information to the `event_url` or `answer_url`.", "enum": [ "GET", "POST" ], "example": "GET" } } } } } }, "messages": { "description": "The Nexmo product that you access with this application.", "type": "object", "properties": { "webhooks": { "type": "array", "items": { "type": "object", "required": [ "endpoint_type", "endpoint", "http_method" ], "properties": { "endpoint_type": { "type": "string", "enum": [ "inbound_url", "status_url" ], "example": "status_url" }, "endpoint": { "type": "string", "description": "`inbound_url`: The URL where inbound messages are delivered. `status_url`: The URL where message status is delivered.", "format": "url", "example": "https://example.com/webhooks/status" }, "http_method": { "type": "string", "description": "The HTTP method used to send data to the `inbound_url` or `status_url`. Default is POST.", "enum": [ "GET", "POST" ], "example": "POST" } } } } } }, "keys": { "description": "The Nexmo product that you access with this application.", "type": "object", "properties": { "public_key": { "description": "The public key used to validate the [JWT](https://en.wikipedia.org/wiki/JSON_Web_Token).", "type": "string", "example": "PUBLIC_KEY" } } }, "keysWithPrivateKey": { "allOf": [ { "$ref": "#/components/schemas/keys" }, { "properties": { "private_key": { "description": "The private key you use to generate the JSON Web Token (JWT) that authenticates your requests to Messages API.", "type": "string", "example": "PRIVATE_KEY" } } } ] }, "applicationCreated": { "allOf": [ { "$ref": "#/components/schemas/application" }, { "properties": { "keys": { "$ref": "#/components/schemas/keysWithPrivateKey" } } } ] }, "application": { "type": "object", "required": [ "name", "voice", "messages" ], "properties": { "id": { "$ref": "#/components/schemas/applicationBase/properties/id" }, "name": { "$ref": "#/components/schemas/applicationBase/properties/name" }, "voice": { "$ref": "#/components/schemas/voice" }, "messages": { "$ref": "#/components/schemas/messages" }, "keys": { "$ref": "#/components/schemas/keys" }, "_links": { "$ref": "#/components/schemas/links" } } }, "applicationBase": { "type": "object", "properties": { "id": { "description": "The ID allocated to your application by Nexmo.", "type": "string", "example": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab" }, "name": { "description": "The name of your application", "type": "string", "example": "My Application" } } }, "applications": { "type": "object", "required": [ "count", "page_size", "page_index", "_embedded", "_links" ], "properties": { "count": { "$ref": "#/components/schemas/applicationsBase/properties/count" }, "page_size": { "$ref": "#/components/schemas/applicationsBase/properties/page_size" }, "page_index": { "$ref": "#/components/schemas/applicationsBase/properties/page_index" }, "_embedded": { "$ref": "#/components/schemas/applicationsBase/properties/_embedded" }, "_links": { "$ref": "#/components/schemas/links" } } }, "applicationsBase": { "properties": { "count": { "description": "The number of items associated with your account.", "type": "integer", "example": 1 }, "page_size": { "description": "The number of items returned on each call to this endpoint. The default is 10 records.", "type": "integer", "example": 10 }, "page_index": { "description": "The offset from the first page.", "type": "integer", "example": 1 }, "_embedded": { "type": "object", "properties": { "applications": { "type": "array", "description": "The collection of your applications. Each object contains information about an an individual application. The public_key is not included in the application information.", "items": { "$ref": "#/components/schemas/application" } } } } } } } } }