{ "openapi": "3.0.0", "info": { "version": "2.4.1", "title": "Application API", "x-metaTitle": "Vonage Application API (v2.0) Reference | Vonage API Documentation", "x-metaDescription": "Find quick answers to questions about the Vonage Application API (v2.0) in this reference guide. Learn more in Vonage's API documentation.", "description": "Vonage provides an Application API to allow management of your Vonage Applications.\n\nThis 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.\n", "contact": { "name": "Vonage", "url": "https://developer.vonage.com/", "email": "devrel@nexmo.com" } }, "servers": [ { "url": "https://api.nexmo.com" } ], "paths": { "/v2/applications": { "get": { "security": [ { "basicAuth": [] } ], "tags": [ "application" ], "operationId": "listApplication", "summary": "List available applications", "parameters": [ { "name": "page_size", "in": "query", "description": "The number of applications per page", "schema": { "type": "integer" } }, { "name": "page", "in": "query", "description": "The current page number (starts at 1)", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplicationResponseCollection" } } } }, "400": { "description": "Invalid Request", "content": { "application/json": { "schema": { "properties": { "type": { "type": "string", "example": "https://developer.vonage.com/api-errors/application#list-validation" }, "title": { "type": "string", "example": "Bad Request" }, "detail": { "type": "string", "example": "The request failed due to validation errors" }, "invalid_parameters": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "example": "page_size" }, "reason": { "type": "string", "example": "must be between 1 and 100" } } } }, "instance": { "$ref": "#/components/schemas/instance" } } } } } }, "401": { "$ref": "#/components/responses/BadCredentialsError" }, "405": { "$ref": "#/components/responses/InvalidRequestMethod" }, "406": { "$ref": "#/components/responses/InvalidAcceptHeader" } } }, "post": { "security": [ { "basicAuth": [] } ], "tags": [ "application" ], "summary": "Create an application", "operationId": "createApplication", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name" ], "properties": { "name": { "description": "Application Name", "example": "Demo Application", "type": "string" }, "keys": { "type": "object", "properties": { "public_key": { "type": "string", "example": "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCA\nKOxjsU4pf/sMFi9N0jqcSLcjxu33G\nd/vynKnlw9SENi+UZR44GdjGdmfm1\ntL1eA7IBh2HNnkYXnAwYzKJoa4eO3\n0kYWekeIZawIwe/g9faFgkev+1xsO\nOUNhPx2LhuLmgwWSRS4L5W851Xe3f\nUQIDAQAB\n-----END PUBLIC KEY-----\n", "description": "Public key" } } }, "capabilities": { "type": "object", "description": "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.", "x-nexmo-developer-collection-description-shown": true, "properties": { "voice": { "type": "object", "description": "Voice application webhook config", "x-nexmo-developer-collection-description-shown": true, "properties": { "webhooks": { "type": "object", "properties": { "answer_url": { "type": "object", "description": "The URL that Vonage makes a request to when a call is placed/received. Must return an NCCO", "x-nexmo-developer-collection-description-shown": true, "properties": { "address": { "type": "string", "example": "https://example.com/webhooks/answer" }, "http_method": { "type": "string", "example": "GET", "enum": [ "GET", "POST" ] }, "connect_timeout": { "type": "integer", "description": "If Vonage can't connect to the webhook URL for this specified amount of time, then Vonage makes one additional attempt to connect to the webhook endpoint. This is an integer value specified in milliseconds.", "example": 500, "default": 1000, "maximum": 1000, "minimum": 300 }, "socket_timeout": { "type": "integer", "description": "If a response from the webhook URL can't be read for this specified amount of time, then Vonage makes one additional attempt to read the webhook endpoint. This is an integer value specified in milliseconds.", "example": 3000, "default": 5000, "maximum": 5000, "minimum": 1000 } } }, "fallback_answer_url": { "type": "object", "description": "If your `answer_url` is offline or returns a HTTP error code, Vonage will make a request to a\n`fallback_answer_url` if it is set. This URL must return an NCCO.\n", "x-nexmo-developer-collection-description-shown": true, "properties": { "address": { "type": "string", "example": "https://fallback.example.com/webhooks/answer" }, "http_method": { "type": "string", "example": "GET", "enum": [ "GET", "POST" ] }, "connect_timeout": { "type": "integer", "description": "If Vonage can't connect to the webhook URL for this specified amount of time, then Vonage makes one additional attempt to connect to the webhook endpoint. This is an integer value specified in milliseconds.", "example": 500, "default": 1000, "maximum": 1000, "minimum": 300 }, "socket_timeout": { "type": "integer", "description": "If a response from the webhook URL can't be read for this specified amount of time, then Vonage makes one additional attempt to read the webhook endpoint. This is an integer value specified in milliseconds.", "example": 3000, "default": 5000, "maximum": 5000, "minimum": 1000 } } }, "event_url": { "type": "object", "description": "Vonage will send call events (e.g. `ringing`, `answered`) to this URL", "x-nexmo-developer-collection-description-shown": true, "properties": { "address": { "type": "string", "example": "https://example.com/webhooks/event" }, "http_method": { "type": "string", "example": "POST", "enum": [ "GET", "POST" ] }, "connect_timeout": { "type": "integer", "description": "If Vonage can't connect to the webhook URL for this specified amount of time, then Vonage makes one additional attempt to connect to the webhook endpoint. This is an integer value specified in milliseconds.", "example": 500, "default": 1000, "maximum": 1000, "minimum": 300 }, "socket_timeout": { "type": "integer", "description": "If a response from the webhook URL can't be read for this specified amount of time, then Vonage makes one additional attempt to read the webhook endpoint. This is an integer value specified in milliseconds.", "example": 3000, "default": 10000, "maximum": 10000, "minimum": 1000 } } } } }, "signed_callbacks": { "description": "Whether to use signed webhooks. This is a way of verifying that the request is coming from Vonage. Refer to [the Webhooks documentation](https://developer.vonage.com/en/getting-started/concepts/webhooks#decoding-signed-webhooks) for more information.", "type": "boolean", "default": "true", "example": false }, "conversations_ttl": { "description": "The length of time named conversations will remain active for after creation, in hours. Maximum value is 9000 (i.e. 365 days).", "type": "integer", "example": 12, "default": 48, "maximum": 9000, "minimum": 1 }, "leg_persistence_time": { "description": "The persistence duration for legs, in days. Maximum value is 31.", "type": "integer", "example": 10, "default": 2, "maximum": 31, "minimum": 1 }, "region": { "$ref": "#/components/schemas/VoiceRegion" } } }, "rtc": { "type": "object", "description": "RTC / Client SDK application webhook config", "x-nexmo-developer-collection-description-shown": true, "properties": { "webhooks": { "type": "object", "properties": { "event_url": { "type": "object", "description": "Vonage will send RTC events to this URL", "x-nexmo-developer-collection-description-shown": true, "properties": { "address": { "type": "string", "example": "https://example.com/webhooks/event" }, "http_method": { "type": "string", "example": "POST", "enum": [ "GET", "POST" ] } } } } }, "signed_callbacks": { "description": "Whether to use signed webhooks. This is a way of verifying that the request is coming from Vonage. Refer to [the Webhooks documentation](https://developer.vonage.com/en/getting-started/concepts/webhooks#decoding-signed-webhooks) for more information.", "type": "boolean", "default": "true", "example": false } } }, "messages": { "type": "object", "description": "Messages and Dispatch application webhook config", "x-nexmo-developer-collection-description-shown": true, "properties": { "version": { "type": "string", "description": "If not populated will be set to v1" }, "webhooks": { "type": "object", "properties": { "inbound_url": { "type": "object", "description": "Vonage will forward inbound messages to this URL", "x-nexmo-developer-collection-description-shown": true, "properties": { "address": { "type": "string", "example": "https://example.com/webhooks/inbound" }, "http_method": { "type": "string", "example": "POST", "enum": [ "POST" ] } } }, "status_url": { "type": "object", "description": "Vonage will send message status updates (e.g. `delivered`, `seen`) to this URL", "x-nexmo-developer-collection-description-shown": true, "properties": { "address": { "type": "string", "example": "https://example.com/webhooks/status" }, "http_method": { "type": "string", "example": "POST", "enum": [ "POST" ] } } } } } } }, "vbc": { "type": "object", "description": "Specify `vbc` capability to enable zero-rated calls for VBC number programmability service applications. This must be an empty object.", "x-nexmo-developer-collection-description-shown": true }, "network_apis": { "type": "object", "description": "Network APIs", "x-nexmo-developer-collection-description-shown": true, "properties": { "network_application_id": { "type": "string", "example": "2bzfIFqRG128IcjSj1YhZNtw6LADG" }, "redirect_uri": { "type": "string", "example": "https://my-redirect-uri.example.com" } } }, "meetings": { "type": "object", "description": "Meetings related configuration", "x-nexmo-developer-collection-description-shown": true, "properties": { "webhooks": { "type": "object", "properties": { "recording_changed": { "type": "object", "description": "The URL that Vonage forwards recording information to on your server", "x-nexmo-developer-collection-description-shown": true, "properties": { "address": { "type": "string", "example": "https://example.com/webhooks/recordings" }, "http_method": { "type": "string", "example": "POST", "enum": [ "POST" ] } } }, "room_changed": { "type": "object", "description": "The URL that Vonage forwards meeting room information on your server.", "x-nexmo-developer-collection-description-shown": true, "properties": { "address": { "type": "string", "example": "https://example.com/webhooks/rooms" }, "http_method": { "type": "string", "example": "POST", "enum": [ "POST" ] } } }, "session_changed": { "type": "object", "description": "The URL that Vonage forwards session information on your server.", "x-nexmo-developer-collection-description-shown": true, "properties": { "address": { "type": "string", "example": "https://example.com/webhooks/sessions" }, "http_method": { "type": "string", "example": "POST", "enum": [ "POST" ] } } } } } } }, "verify": { "type": "object", "description": "Verify v2 application webhook config", "x-nexmo-developer-collection-description-shown": true, "properties": { "webhooks": { "type": "object", "properties": { "status_url": { "type": "object", "description": "Vonage will send Verify updates to this URL", "x-nexmo-developer-collection-description-shown": true, "properties": { "address": { "type": "string", "example": "https://example.com/webhooks/status" }, "http_method": { "type": "string", "example": "POST", "enum": [ "POST" ] } } } } } } }, "video": { "$ref": "#/components/schemas/VideoResponse" } } }, "privacy": { "type": "object", "description": "Application privacy config", "properties": { "improve_ai": { "type": "boolean", "description": "If set to `true`, Vonage may store and use your content and data for the improvement of Vonage's AI based services and technologies.", "example": true, "default": true } } } } } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApplicationResponse" }, { "type": "object", "properties": { "keys": { "type": "object", "properties": { "public_key": { "type": "string", "example": "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCA\nKOxjsU4pf/sMFi9N0jqcSLcjxu33G\nd/vynKnlw9SENi+UZR44GdjGdmfm1\ntL1eA7IBh2HNnkYXnAwYzKJoa4eO3\n0kYWekeIZawIwe/g9faFgkev+1xsO\nOUNhPx2LhuLmgwWSRS4L5W851Xe3f\nUQIDAQAB\n-----END PUBLIC KEY-----\n" }, "private_key": { "type": "string", "example": "-----BEGIN PRIVATE KEY-----\nMIIEvQIBADANBgkqhkiG9w0BAQEFA\nASCBKcwggSjAgEAAoIBAQDEPpvi+3\nRH1efQ\\nkveWzZDrNNoEXmBw61w+O\n0u/N36tJnN5XnYecU64yHzu2ByEr0\n7iIvYbavFnADwl\\nHMTJwqDQakpa3\n8/SFRnTDq3zronvNZ6nOp7S6K7pcZ\nrw/CvrL6hXT1x7cGBZ4jPx\\nqhjqY\nuJPgZD7OVB69oYOV92vIIJ7JLYwqb\n-----END PRIVATE KEY-----\n" } } } } } ] } } } }, "400": { "$ref": "#/components/responses/InvalidPayloadError" }, "401": { "$ref": "#/components/responses/BadCredentialsError" }, "405": { "$ref": "#/components/responses/InvalidRequestMethod" }, "406": { "$ref": "#/components/responses/InvalidAcceptHeader" }, "415": { "$ref": "#/components/responses/UnsupportedContentTypeHeader" } } } }, "/v2/applications/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The ID of the application", "example": "78d335fa-323d-0114-9c3d-d6f0d48968cf", "schema": { "type": "string" } } ], "get": { "security": [ { "basicAuth": [] } ], "tags": [ "application" ], "operationId": "getApplication", "summary": "Get an application", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplicationResponse" } } } }, "401": { "$ref": "#/components/responses/BadCredentialsError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "405": { "$ref": "#/components/responses/InvalidRequestMethod" }, "406": { "$ref": "#/components/responses/InvalidAcceptHeader" } } }, "put": { "security": [ { "basicAuth": [] } ], "tags": [ "application" ], "summary": "Update an application", "operationId": "updateApplication", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name" ], "properties": { "name": { "description": "Application Name", "example": "Demo Application", "type": "string" }, "keys": { "type": "object", "properties": { "public_key": { "type": "string", "example": "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCA\nKOxjsU4pf/sMFi9N0jqcSLcjxu33G\nd/vynKnlw9SENi+UZR44GdjGdmfm1\ntL1eA7IBh2HNnkYXnAwYzKJoa4eO3\n0kYWekeIZawIwe/g9faFgkev+1xsO\nOUNhPx2LhuLmgwWSRS4L5W851Xe3f\nUQIDAQAB\n-----END PUBLIC KEY-----\n", "description": "Public key" } } }, "capabilities": { "type": "object", "description": "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.", "x-nexmo-developer-collection-description-shown": true, "properties": { "voice": { "type": "object", "description": "Voice application webhook config", "x-nexmo-developer-collection-description-shown": true, "properties": { "webhooks": { "type": "object", "properties": { "answer_url": { "type": "object", "description": "The URL that Vonage make a request to when a call is placed/received. Must return an NCCO", "x-nexmo-developer-collection-description-shown": true, "properties": { "address": { "type": "string", "example": "https://example.com/webhooks/answer" }, "http_method": { "type": "string", "example": "GET", "enum": [ "GET", "POST" ] }, "connect_timeout": { "type": "integer", "description": "If Vonage can't connect to the webhook URL for this specified amount of time, then Vonage makes one additional attempt to connect to the webhook endpoint. This is an integer value specified in milliseconds.", "example": 500, "default": 1000, "maximum": 1000, "minimum": 300 }, "socket_timeout": { "type": "integer", "description": "If a response from the webhook URL can't be read for this specified amount of time, then Vonage makes one additional attempt to read the webhook endpoint. This is an integer value specified in milliseconds.", "example": 3000, "default": 5000, "maximum": 5000, "minimum": 1000 } } }, "fallback_answer_url": { "type": "object", "description": "If your `answer_url` is offline or returns a HTTP error code, Vonage will make a request to a\n`fallback_answer_url` if it is set. This URL must return an NCCO\n", "x-nexmo-developer-collection-description-shown": true, "properties": { "address": { "type": "string", "example": "https://fallback.example.com/webhooks/answer" }, "http_method": { "type": "string", "example": "GET", "enum": [ "GET", "POST" ] }, "connect_timeout": { "type": "integer", "description": "If Vonage can't connect to the webhook URL for this specified amount of time, then Vonage makes one additional attempt to connect to the webhook endpoint. This is an integer value specified in milliseconds.", "example": 500, "default": 1000, "maximum": 1000, "minimum": 300 }, "socket_timeout": { "type": "integer", "description": "If a response from the webhook URL can't be read for this specified amount of time, then Vonage makes one additional attempt to read the webhook endpoint. This is an integer value specified in milliseconds.", "example": 3000, "default": 5000, "maximum": 5000, "minimum": 1000 } } }, "event_url": { "type": "object", "description": "Vonage will send call events (e.g. `ringing`, `answered`) to this URL", "x-nexmo-developer-collection-description-shown": true, "properties": { "address": { "type": "string", "example": "https://example.com/webhooks/event" }, "http_method": { "type": "string", "example": "POST", "enum": [ "GET", "POST" ] }, "connect_timeout": { "type": "integer", "description": "If Vonage can't connect to the webhook URL for this specified amount of time, then Vonage makes one additional attempt to connect to the webhook endpoint. This is an integer value specified in milliseconds.", "example": 500, "default": 1000, "maximum": 1000, "minimum": 300 }, "socket_timeout": { "type": "integer", "description": "If a response from the webhook URL can't be read for this specified amount of time, then Vonage makes one additional attempt to read the webhook endpoint. This is an integer value specified in milliseconds.", "example": 3000, "default": 10000, "maximum": 10000, "minimum": 1000 } } } } }, "signed_callbacks": { "description": "Whether to use signed webhooks. This is a way of verifying that the request is coming from Vonage. Refer to [the Webhooks documentation](https://developer.vonage.com/en/getting-started/concepts/webhooks#decoding-signed-webhooks) for more information.", "type": "boolean", "default": "true", "example": false }, "conversations_ttl": { "description": "The length of time named conversations will remain active for after creation, in hours. Maximum value is 9000 (i.e. 365 days).", "type": "integer", "example": 12, "default": 48, "maximum": 9000, "minimum": 1 }, "leg_persistence_time": { "description": "The persistence duration for legs, in days. Maximum value is 31.", "type": "integer", "example": 10, "default": 2, "maximum": 31, "minimum": 1 }, "region": { "$ref": "#/components/schemas/VoiceRegion" } } }, "rtc": { "type": "object", "description": "RTC / Client SDK application webhook config", "x-nexmo-developer-collection-description-shown": true, "properties": { "webhooks": { "type": "object", "properties": { "event_url": { "type": "object", "description": "Vonage will send RTC events to this URL", "x-nexmo-developer-collection-description-shown": true, "properties": { "address": { "type": "string", "example": "https://example.com/webhooks/event" }, "http_method": { "type": "string", "example": "POST", "enum": [ "GET", "POST" ] } } } } }, "signed_callbacks": { "description": "Whether to use signed webhooks. This is a way of verifying that the request is coming from Vonage. Refer to [the Webhooks documentation](https://developer.vonage.com/en/getting-started/concepts/webhooks#decoding-signed-webhooks) for more information.", "type": "boolean", "default": "true", "example": false } } }, "messages": { "type": "object", "description": "Messages and Dispatch application webhook config", "x-nexmo-developer-collection-description-shown": true, "properties": { "webhooks": { "type": "object", "properties": { "inbound_url": { "type": "object", "description": "Vonage will forward inbound messages to this URL", "x-nexmo-developer-collection-description-shown": true, "properties": { "address": { "type": "string", "example": "https://example.com/webhooks/inbound" }, "http_method": { "type": "string", "example": "POST", "enum": [ "POST" ] } } }, "status_url": { "type": "object", "description": "Vonage will send message status updates (e.g. `delivered`, `seen`) to this URL", "x-nexmo-developer-collection-description-shown": true, "properties": { "address": { "type": "string", "example": "https://example.com/webhooks/status" }, "http_method": { "type": "string", "example": "POST", "enum": [ "POST" ] } } } } } } }, "vbc": { "type": "object", "description": "Specify the `vbc` capability to enable zero-rated calls for VBC number programmability service applications. This must be an empty object.", "x-nexmo-developer-collection-description-shown": true }, "network_apis": { "type": "object", "description": "Network APIs", "x-nexmo-developer-collection-description-shown": true, "properties": { "network_application_id": { "type": "string", "example": "2bzfIFqRG128IcjSj1YhZNtw6LADG" }, "redirect_uri": { "type": "string", "example": "https://my-redirect-uri.example.com" } } }, "meetings": { "type": "object", "description": "Meetings related configuration", "x-nexmo-developer-collection-description-shown": true, "properties": { "webhooks": { "type": "object", "properties": { "recording_url": { "type": "object", "description": "The URL that Vonage forwards recording information to on your server", "x-nexmo-developer-collection-description-shown": true, "properties": { "address": { "type": "string", "example": "https://example.com/webhooks/recordings" }, "http_method": { "type": "string", "example": "POST", "enum": [ "POST" ] } } }, "rooms_url": { "type": "object", "description": "The URL that Vonage forwards meeting room information on your server.", "x-nexmo-developer-collection-description-shown": true, "properties": { "address": { "type": "string", "example": "https://example.com/webhooks/rooms" }, "http_method": { "type": "string", "example": "POST", "enum": [ "POST" ] } } }, "sessions_url": { "type": "object", "description": "The URL that Vonage forwards session information on your server.", "x-nexmo-developer-collection-description-shown": true, "properties": { "address": { "type": "string", "example": "https://example.com/webhooks/sessions" }, "http_method": { "type": "string", "example": "POST", "enum": [ "POST" ] } } } } } } }, "video": { "$ref": "#/components/schemas/VideoResponse" } } }, "privacy": { "type": "object", "description": "Application privacy config", "properties": { "improve_ai": { "type": "boolean", "description": "If set to `true`, Vonage may store and use your content and data for the improvement of Vonage's AI based services and technologies.", "example": true } } } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApplicationResponse" }, { "type": "object", "properties": { "keys": { "type": "object", "properties": { "public_key": { "type": "string", "example": "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCA\nKOxjsU4pf/sMFi9N0jqcSLcjxu33G\nd/vynKnlw9SENi+UZR44GdjGdmfm1\ntL1eA7IBh2HNnkYXnAwYzKJoa4eO3\n0kYWekeIZawIwe/g9faFgkev+1xsO\nOUNhPx2LhuLmgwWSRS4L5W851Xe3f\nUQIDAQAB\n-----END PUBLIC KEY-----\n" }, "private_key": { "type": "string", "example": "-----BEGIN PRIVATE KEY-----\nMIIEvQIBADANBgkqhkiG9w0BAQEFA\nASCBKcwggSjAgEAAoIBAQDEPpvi+3\nRH1efQ\\nkveWzZDrNNoEXmBw61w+O\n0u/N36tJnN5XnYecU64yHzu2ByEr0\n7iIvYbavFnADwl\\nHMTJwqDQakpa3\n8/SFRnTDq3zronvNZ6nOp7S6K7pcZ\nrw/CvrL6hXT1x7cGBZ4jPx\\nqhjqY\nuJPgZD7OVB69oYOV92vIIJ7JLYwqb\n-----END PRIVATE KEY-----\n" } } } } } ] } } } }, "400": { "$ref": "#/components/responses/InvalidPayloadError" }, "401": { "$ref": "#/components/responses/BadCredentialsError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "405": { "$ref": "#/components/responses/InvalidRequestMethod" }, "406": { "$ref": "#/components/responses/InvalidAcceptHeader" }, "415": { "$ref": "#/components/responses/UnsupportedContentTypeHeader" } } }, "delete": { "security": [ { "basicAuth": [] } ], "tags": [ "application" ], "operationId": "deleteApplication", "summary": "Delete an application", "description": "Deleting an application **cannot be undone**.", "responses": { "204": { "description": "Success" }, "401": { "$ref": "#/components/responses/BadCredentialsError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "405": { "$ref": "#/components/responses/InvalidRequestMethod" }, "406": { "$ref": "#/components/responses/InvalidAcceptHeader" } } } }, "/v1/users": { "get": { "security": [ { "bearerAuth": [] } ], "operationId": "getUsers", "tags": [ "user" ], "summary": "List users", "parameters": [ { "$ref": "#/components/parameters/page_size" }, { "$ref": "#/components/parameters/order" }, { "$ref": "#/components/parameters/cursor" }, { "$ref": "#/components/parameters/user_name" } ], "responses": { "200": { "description": "List of users", "content": { "application/json": { "schema": { "type": "object", "properties": { "page_size": { "$ref": "#/components/schemas/page_size" }, "_embedded": { "description": "A list of user objects. See the [get details of a specific user](#getUser) response fields for a description of the nested objects", "type": "object", "x-nexmo-developer-collection-description-shown": true, "properties": { "users": { "type": "array", "description": "List of users matching the provided filter", "items": { "$ref": "#/components/schemas/user_lite" } } }, "required": [ "users" ] }, "_links": { "type": "object", "description": "A series of links between resources in this API in the http://stateless.co/hal_specification.html.", "properties": { "first": { "type": "object", "properties": { "href": { "type": "string", "example": "https://api.nexmo.com/v1/users?order=desc&page_size=10" } } }, "self": { "type": "object", "properties": { "href": { "type": "string", "example": "https://api.nexmo.com/v1/users?order=desc&page_size=10&cursor=7EjDNQrAcipmOnc0HCzpQRkhBULzY44ljGUX4lXKyUIVfiZay5pv9wg%3D" } } }, "next": { "type": "object", "properties": { "href": { "type": "string", "example": "https://api.nexmo.com/v1/users?order=desc&page_size=10&cursor=7EjDNQrAcipmOnc0HCzpQRkhBULzY44ljGUX4lXKyUIVfiZay5pv9wg%3D" } } }, "prev": { "type": "object", "properties": { "href": { "type": "string", "example": "https://api.nexmo.com/v1/users?order=desc&page_size=10&cursor=7EjDNQrAcipmOnc0HCzpQRkhBULzY44ljGUX4lXKyUIVfiZay5pv9wg%3D" } } } }, "required": [ "first", "self" ] } }, "required": [ "cursor", "page_size", "_embedded", "_links" ] } } } }, "400": { "$ref": "#/components/responses/General400ValidationFailPageSize" }, "401": { "$ref": "#/components/responses/General401InvalidToken" }, "404": { "$ref": "#/components/responses/User404" }, "406": { "$ref": "#/components/responses/User406ValidationFailContentType" }, "429": { "$ref": "#/components/responses/General429TooManyRequests" }, "500": { "$ref": "#/components/responses/General500InternalError" } } }, "post": { "security": [ { "bearerAuth": [] } ], "operationId": "createUser", "tags": [ "user" ], "summary": "Create a user", "description": "Note: Users must be created with an admin JWT.", "responses": { "201": { "description": "Create a user response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/user" } } } }, "400": { "$ref": "#/components/responses/General400ValidationFailName" }, "401": { "$ref": "#/components/responses/General401InvalidToken" }, "406": { "$ref": "#/components/responses/User406ValidationFailContentType" }, "429": { "$ref": "#/components/responses/General429TooManyRequests" }, "500": { "$ref": "#/components/responses/General500InternalError" } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "description": "Create a User", "properties": { "name": { "$ref": "#/components/schemas/user_name" }, "display_name": { "$ref": "#/components/schemas/user_display_name" }, "image_url": { "$ref": "#/components/schemas/user_image_url" }, "properties": { "$ref": "#/components/schemas/user_properties" }, "channels": { "$ref": "#/components/schemas/user_channels" } } } } } } } }, "/v1/users/{id}": { "get": { "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/user_id_name" } ], "operationId": "getUser", "tags": [ "user" ], "summary": "Retrieve a user", "responses": { "200": { "description": "Retrieve a user", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/user" } } } }, "401": { "$ref": "#/components/responses/General401InvalidToken" }, "404": { "$ref": "#/components/responses/User404" }, "406": { "$ref": "#/components/responses/User406ValidationFailContentType" }, "429": { "$ref": "#/components/responses/General429TooManyRequests" }, "500": { "$ref": "#/components/responses/General500InternalError" } } }, "patch": { "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/user_id" } ], "operationId": "updateUser", "tags": [ "user" ], "summary": "Update a user", "responses": { "200": { "description": "Update a user", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/user" } } } }, "400": { "$ref": "#/components/responses/General400ValidationFailName" }, "401": { "$ref": "#/components/responses/General401InvalidToken" }, "404": { "$ref": "#/components/responses/User404" }, "406": { "$ref": "#/components/responses/User406ValidationFailContentType" }, "429": { "$ref": "#/components/responses/General429TooManyRequests" }, "500": { "$ref": "#/components/responses/General500InternalError" } }, "requestBody": { "content": { "application/json": { "schema": { "properties": { "name": { "$ref": "#/components/schemas/user_name" }, "display_name": { "$ref": "#/components/schemas/user_display_name" }, "image_url": { "$ref": "#/components/schemas/user_image_url" }, "channels": { "$ref": "#/components/schemas/user_channels" } } } } } } }, "delete": { "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/user_id" } ], "operationId": "deleteUser", "tags": [ "user" ], "summary": "Delete a user", "description": "Deleting a user **cannot be undone**.", "responses": { "204": { "$ref": "#/components/responses/General204" }, "400": { "$ref": "#/components/responses/General400ValidationFailName" }, "401": { "$ref": "#/components/responses/General401InvalidToken" }, "404": { "$ref": "#/components/responses/User404" }, "406": { "$ref": "#/components/responses/User406ValidationFailContentType" }, "429": { "$ref": "#/components/responses/General429TooManyRequests" }, "500": { "$ref": "#/components/responses/General500InternalError" } } } } }, "components": { "securitySchemes": { "basicAuth": { "type": "http", "scheme": "basic" }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" } }, "responses": { "InvalidPayloadError": { "description": "Invalid Request", "content": { "application/json": { "schema": { "properties": { "type": { "type": "string", "example": "https://developer.vonage.com/api-errors/application#payload-validation" }, "title": { "type": "string", "example": "Bad Request" }, "detail": { "type": "string", "example": "The request failed due to validation errors" }, "invalid_parameters": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "example": "capabilities.voice.webhooks.answer_url.http_method" }, "reason": { "type": "string", "example": "must be one of: GET, POST" } } } }, "instance": { "$ref": "#/components/schemas/instance" } } } } } }, "General204": { "description": "Success response with no content" }, "General400ValidationFailPageSize": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "example": "Bad request." }, "type": { "type": "string", "example": "https://developer.vonage.com/api/conversation#http:error:validation-fail" }, "code": { "type": "string", "example": "http:error:validation-fail" }, "detail": { "type": "string", "example": "Input validation failure." }, "instance": { "type": "string", "example": "00a5916655d650e920ccf0daf40ef4ee" }, "invalid_parameters": { "type": "array", "description": "List of invalid parameters", "items": { "type": "object", "properties": { "name": { "type": "string", "example": "page_size" }, "reason": { "type": "string", "example": "\"page_size\" must be a number" } } } } } } } } }, "General400ValidationFailName": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "example": "Bad request." }, "type": { "type": "string", "example": "https://developer.vonage.com/api/conversation#http:error:validation-fail" }, "code": { "type": "string", "example": "http:error:validation-fail" }, "detail": { "type": "string", "example": "Input validation failure." }, "instance": { "type": "string", "example": "00a5916655d650e920ccf0daf40ef4ee" }, "invalid_parameters": { "type": "array", "description": "List of invalid parameters", "items": { "type": "object", "properties": { "name": { "type": "string", "example": "name" }, "reason": { "type": "string", "example": "\"name\" must be a string" } } } } } } } } }, "General401InvalidToken": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "example": "Unauthorized." }, "type": { "type": "string", "example": "https://developer.vonage.com/api/conversation#system:error:invalid-token" }, "code": { "type": "string", "example": "system:error:invalid-token" }, "detail": { "type": "string", "example": "You did not provide a valid token. Please provide a valid token." }, "instance": { "type": "string", "example": "00a5916655d650e920ccf0daf40ef4ee" } } } } } }, "User404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "example": "Not found." }, "type": { "type": "string", "example": "https://developer.vonage.com/api/conversation#user:error:not-found" }, "code": { "type": "string", "example": "user:error:not-found" }, "detail": { "type": "string", "example": "User does not exist, or you do not have access." }, "instance": { "type": "string", "example": "00a5916655d650e920ccf0daf40ef4ee" } } } } } }, "User406ValidationFailContentType": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "example": "Bad request." }, "type": { "type": "string", "example": "https://developer.vonage.com/api/conversation#http:error:validation-fail" }, "code": { "type": "string", "example": "http:error:validation-fail" }, "detail": { "type": "string", "example": "Invalid Content-Type." }, "instance": { "type": "string", "example": "00a5916655d650e920ccf0daf40ef4ee" }, "invalid_parameters": { "type": "array", "description": "List of invalid parameters", "items": { "type": "object", "properties": { "name": { "type": "string", "example": "content-type" }, "reason": { "type": "string", "example": "content-type \\\"application/xml\\\" is not supported. Supported versions are [application/json]" } } } } } } } } }, "General429TooManyRequests": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "example": "Too Many Requests." }, "type": { "type": "string", "example": "https://developer.vonage.com/api/conversation#http:error:too-many-request" }, "code": { "type": "string", "example": "http:error:too-many-request" }, "detail": { "type": "string", "example": "You have exceeded your request limit. You can try again shortly." }, "instance": { "type": "string", "example": "00a5916655d650e920ccf0daf40ef4ee" } } } } } }, "General500InternalError": { "description": "Internal Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "example": "Internal Error." }, "type": { "type": "string", "example": "https://developer.vonage.com/api/conversation#system:error:internal-error" }, "code": { "type": "string", "example": "system:error:internal-error" }, "detail": { "type": "string", "example": "Something went wrong." }, "instance": { "type": "string", "example": "00a5916655d650e920ccf0daf40ef4ee" } } } } } }, "BadCredentialsError": { "description": "Credential is missing or invalid", "content": { "application/json": { "schema": { "properties": { "type": { "type": "string", "example": "https://developer.vonage.com/api-errors#unauthorized" }, "title": { "type": "string", "example": "Invalid credentials supplied" }, "detail": { "type": "string", "example": "You did not provide correct credentials." }, "instance": { "$ref": "#/components/schemas/instance" } } } } } }, "InvalidRequestMethod": { "description": "Invalid Request Method", "content": { "application/json": { "schema": { "properties": { "type": { "type": "string", "example": "https://developer.vonage.com/api-errors#wrong-verb" }, "title": { "type": "string", "example": "Request method not allowed" }, "detail": { "type": "string", "example": "Request method 'TRACE' not supported" }, "instance": { "$ref": "#/components/schemas/instance" } } } } } }, "InvalidAcceptHeader": { "description": "Invalid Accept Header", "content": { "application/json": { "schema": { "properties": { "type": { "type": "string", "example": "https://developer.vonage.com/api-errors#accept-header" }, "title": { "type": "string", "example": "Invalid Accept header" }, "detail": { "type": "string", "example": "Invalid Accept header provided. Must be one of the following: 'application/json'" }, "instance": { "$ref": "#/components/schemas/instance" } } } } } }, "UnsupportedContentTypeHeader": { "description": "Unsupported Content Type Header", "content": { "application/json": { "schema": { "properties": { "type": { "type": "string", "example": "https://developer.vonage.com/api-errors#content-type-header" }, "title": { "type": "string", "example": "Unsupported Content-Type header" }, "detail": { "type": "string", "example": "Unsupported Content-Type header provided. Must be one of the following: 'application/json'" }, "instance": { "$ref": "#/components/schemas/instance" } } } } } }, "NotFoundError": { "description": "Resource Not Found", "content": { "application/json": { "schema": { "properties": { "type": { "type": "string", "example": "https://developer.vonage.com/api-errors#not-found" }, "title": { "type": "string", "example": "Not Found" }, "detail": { "type": "string", "example": "ID 'ABC123' does not exist, or you do not have access" }, "instance": { "$ref": "#/components/schemas/instance" } } } } } } }, "schemas": { "VoiceRegion": { "description": "Selecting a region means all inbound, programmable SIP and SIP connect calls will be sent to the selected region unless the call is sent to a regional endpoint, if the call is using a regional endpoint this will override the application setting. Use the following parameter values:\n * **na-east** - North America - East (api-us-3.vonage.com)\n * **na-west** - North America - West (api-us-4.vonage.com)\n * **eu-east** - Europe - East (api-eu-4.vonage.com)\n * **eu-west** - Europe - West (api-eu-3.vonage.com)\n * **apac-sng** - Singapore (api-ap-3.vonage.com)\n * **apac-australia** - Australia (api-ap-4.vonage.com)\n", "type": "string", "example": "eu-west", "enum": [ "na-east", "na-west", "eu-east", "eu-west", "apac-sng", "apac-australia" ] }, "ApplicationResponseCollection": { "properties": { "page_size": { "type": "integer", "example": 10, "description": "The number of applications per page" }, "page": { "type": "integer", "example": 1, "description": "The current page number (starts at 1)" }, "total_items": { "type": "integer", "example": 6, "description": "The total number of applications" }, "total_pages": { "type": "integer", "example": 1, "description": "The total number of pages returned" }, "_embedded": { "type": "object", "description": "A list of applications matching your existing filters", "properties": { "applications": { "type": "array", "items": { "$ref": "#/components/schemas/ApplicationResponse" } } } } } }, "ApplicationResponse": { "properties": { "id": { "type": "string", "example": "78d335fa-323d-0114-9c3d-d6f0d48968cf", "description": "The application's ID" }, "name": { "type": "string", "example": "My Application", "description": "Friendly identifier for your application. This is not unique" }, "capabilities": { "type": "object", "description": "Configuration for the products available in this application", "properties": { "voice": { "type": "object", "description": "Voice related configuration", "properties": { "webhooks": { "type": "object", "properties": { "answer_url": { "type": "object", "properties": { "address": { "type": "string", "example": "https://example.com/webhooks/answer", "description": "The URL that Vonage requests when a call is placed/received. Must return an NCCO" }, "http_method": { "type": "string", "example": "POST", "description": "The HTTP method used to fetch your NCCO from your `answer_url`" }, "connect_timeout": { "type": "integer", "description": "If Vonage can't connect to the webhook URL for this specified amount of time, then Vonage makes one additional attempt to connect to the webhook endpoint. This is an integer value specified in milliseconds.", "example": 500 }, "socket_timeout": { "type": "integer", "description": "If a response from the webhook URL can't be read for this specified amount of time, then Vonage makes one additional attempt to read the webhook endpoint. This is an integer value specified in milliseconds.", "example": 3000 } } }, "fallback_answer_url": { "type": "object", "properties": { "address": { "type": "string", "example": "https://fallback.example.com/webhooks/answer", "description": "If your `answer_url` is offline or returns a HTTP error code, Vonage will make a request to a\n`fallback_answer_url` if it is set. This URL must return an NCCO.\n" }, "http_method": { "type": "string", "example": "POST", "description": "The HTTP method used to fetch your NCCO from your `answer_url`" }, "connect_timeout": { "type": "integer", "description": "Connection timeout in milliseconds", "example": 500 }, "socket_timeout": { "type": "integer", "description": "Reading timeout in milliseconds", "example": 3000 } } }, "event_url": { "type": "object", "properties": { "address": { "type": "string", "example": "https://example.com/webhooks/event", "description": "The URL that Vonage sends events related to your call to" }, "http_method": { "type": "string", "example": "POST", "description": "The HTTP method used to send events to your server" }, "connect_timeout": { "type": "integer", "description": "If Vonage can't connect to the webhook URL for this specified amount of time, then Vonage makes one additional attempt to connect to the webhook endpoint. This is an integer value specified in milliseconds.", "example": 500 }, "socket_timeout": { "type": "integer", "description": "If a response from the webhook URL can't be read for this specified amount of time, then Vonage makes one additional attempt to read the webhook endpoint. This is an integer value specified in milliseconds.", "example": 3000 } } } } }, "signed_callbacks": { "description": "Whether to use signed webhooks. This is a way of verifying that the request is coming from Vonage. Refer to [the Webhooks documentation](https://developer.vonage.com/en/getting-started/concepts/webhooks#decoding-signed-webhooks) for more information.", "type": "boolean", "default": "true", "example": false }, "conversations_ttl": { "description": "The length of time named conversations will remain active for after creation, in hours. Maximum value is 9000 (i.e. 365 days).", "type": "integer", "example": 12, "default": 48, "maximum": 9000, "minimum": 1 }, "leg_persistence_time": { "description": "The persistence duration for legs, in days. Maximum value is 31.", "type": "integer", "example": 10, "default": 2, "maximum": 31, "minimum": 1 }, "region": { "$ref": "#/components/schemas/VoiceRegion" } } }, "messages": { "type": "object", "description": "Messages / Dispatch related configuration", "properties": { "webhooks": { "type": "object", "properties": { "inbound_url": { "type": "object", "properties": { "address": { "type": "string", "example": "https://example.com/webhooks/inbound", "description": "The URL that Vonage forwards inbound messages to on your server" }, "http_method": { "type": "string", "example": "POST", "description": "The HTTP method used to send inbound messages to your server" } } }, "status_url": { "type": "object", "properties": { "address": { "type": "string", "example": "https://example.com/webhooks/status", "description": "The URL that Vonage sends events related to your messages to" }, "http_method": { "type": "string", "example": "POST", "description": "The HTTP method used to send events to your server (always `POST`)" } } } } } } }, "rtc": { "type": "object", "description": "RTC / Conversation Service related configuration", "properties": { "webhooks": { "type": "object", "properties": { "event_url": { "type": "object", "properties": { "address": { "type": "string", "example": "https://example.com/webhooks/event" }, "http_method": { "type": "string", "example": "POST" } } } } }, "signed_callbacks": { "description": "Whether to use signed webhooks. This is a way of verifying that the request is coming from Vonage. Refer to [the Webhooks documentation](https://developer.vonage.com/en/getting-started/concepts/webhooks#decoding-signed-webhooks) for more information.", "type": "boolean", "default": "true", "example": false } } }, "vbc": { "type": "object", "description": "Specify the `vbc` capability to enable zero-rated calls for VBC number programmability service applications. This is always an empty object." }, "network_apis": { "type": "object", "description": "Network APIs", "properties": { "network_application_id": { "type": "string", "example": "2bzfIFqRG128IcjSj1YhZNtw6LADG" }, "redirect_uri": { "type": "string", "example": "https://my-redirect-uri.example.com" } } }, "meetings": { "type": "object", "description": "Meetings related configuration", "properties": { "webhooks": { "type": "object", "properties": { "recording_changed": { "type": "object", "properties": { "address": { "type": "string", "example": "https://example.com/webhooks/recordings", "description": "The URL that Vonage forwards recording information to on your server" }, "http_method": { "type": "string", "example": "POST", "description": "The HTTP method used to send recording information to your server (always `POST`)" } } }, "room_changed": { "type": "object", "properties": { "address": { "type": "string", "example": "https://example.com/webhooks/rooms", "description": "The URL that Vonage forwards meeting room information on your server." }, "http_method": { "type": "string", "example": "POST", "description": "The HTTP method used to send meeting room information to your server (always `POST`)" } } }, "session_changed": { "type": "object", "properties": { "address": { "type": "string", "example": "https://example.com/webhooks/sessions", "description": "The URL that Vonage forwards session information on your server." }, "http_method": { "type": "string", "example": "POST", "description": "The HTTP method used to send session information to your server (always `POST`)" } } } } } } }, "verify": { "type": "object", "description": "Verify v2 related configuration", "properties": { "version": { "type": "string", "example": "v2", "description": "The version of the Verify API to use" }, "webhooks": { "type": "object", "properties": { "status_url": { "type": "object", "properties": { "address": { "type": "string", "example": "https://example.com/webhooks/status", "description": "The URL that Vonage sends events related to your verify requests to" }, "http_method": { "type": "string", "example": "POST", "description": "The HTTP method used to send events to your server (always `POST`)" } } } } } } }, "video": { "$ref": "#/components/schemas/VideoResponse" } } }, "privacy": { "type": "object", "description": "Application privacy config", "properties": { "improve_ai": { "type": "boolean", "description": "If set to `true`, Vonage may store and use your content and data for the improvement of Vonage's AI based services and technologies.", "example": true } } } } }, "VideoResponse": { "type": "object", "description": "Video related configuration", "properties": { "webhooks": { "type": "object", "properties": { "archive_status": { "type": "object", "properties": { "address": { "type": "string", "example": "https://example.com/webhooks/event", "description": "The URL that Vonage sends events informing about the archive status" }, "active": { "$ref": "#/components/schemas/active_webhook" } } }, "connection_created": { "type": "object", "properties": { "address": { "type": "string", "example": "https://example.com/webhooks/event", "description": "The URL that Vonage sends events when a video connection is created" }, "active": { "$ref": "#/components/schemas/active_webhook" } } }, "connection_destroyed": { "type": "object", "properties": { "address": { "type": "string", "example": "https://example.com/webhooks/event", "description": "The URL that Vonage sends events when a video connection is destroyed" }, "active": { "$ref": "#/components/schemas/active_webhook" } } }, "session_created": { "type": "object", "properties": { "address": { "type": "string", "example": "https://example.com/webhooks/event", "description": "The URL that Vonage sends events when a video session is created" }, "active": { "$ref": "#/components/schemas/active_webhook" } } }, "session_destroyed": { "type": "object", "properties": { "address": { "type": "string", "example": "https://example.com/webhooks/event", "description": "The URL that Vonage sends events when a video session is destroyed" }, "active": { "$ref": "#/components/schemas/active_webhook" } } }, "session_notification": { "type": "object", "properties": { "address": { "type": "string", "example": "https://example.com/webhooks/event", "description": "The URL that Vonage sends session notifications to" }, "active": { "$ref": "#/components/schemas/active_webhook" } } }, "stream_created": { "type": "object", "properties": { "address": { "type": "string", "example": "https://example.com/webhooks/event", "description": "The URL that Vonage sends events when a stream is created" }, "active": { "$ref": "#/components/schemas/active_webhook" } } }, "stream_destroyed": { "type": "object", "properties": { "address": { "type": "string", "example": "https://example.com/webhooks/event", "description": "The URL that Vonage sends events when a stream is destroyed" }, "active": { "$ref": "#/components/schemas/active_webhook" } } }, "render_status": { "type": "object", "properties": { "address": { "type": "string", "example": "https://example.com/webhooks/event", "description": "The URL that Vonage sends events when a render status changes" }, "active": { "$ref": "#/components/schemas/active_webhook" } } }, "captions_status": { "type": "object", "properties": { "address": { "type": "string", "example": "https://example.com/webhooks/event", "description": "The URL that Vonage sends events when captions status changes" }, "active": { "$ref": "#/components/schemas/active_webhook" } } }, "broadcast_status": { "type": "object", "properties": { "address": { "type": "string", "example": "https://example.com/webhooks/event", "description": "The URL that Vonage sends events when a broadcast status changes" }, "active": { "$ref": "#/components/schemas/active_webhook" } } }, "sip_call_created": { "type": "object", "properties": { "address": { "type": "string", "example": "https://example.com/webhooks/event", "description": "The URL that Vonage sends events when a sip call is created" }, "active": { "$ref": "#/components/schemas/active_webhook" } } }, "sip_call_updated": { "type": "object", "properties": { "address": { "type": "string", "example": "https://example.com/webhooks/event", "description": "The URL that Vonage sends events when a sip call is updated" }, "active": { "$ref": "#/components/schemas/active_webhook" } } }, "sip_call_destroyed": { "type": "object", "properties": { "address": { "type": "string", "example": "https://example.com/webhooks/event", "description": "The URL that Vonage sends events when a sip call is destroyed" }, "active": { "$ref": "#/components/schemas/active_webhook" } } }, "sip_call_mute_forced": { "type": "object", "properties": { "address": { "type": "string", "example": "https://example.com/webhooks/event", "description": "The URL that Vonage sends events when a sip call is muted" }, "active": { "$ref": "#/components/schemas/active_webhook" } } } } }, "storage": { "type": "object", "properties": { "server_side_encryption": { "type": "boolean", "example": false, "description": "Whether to use server-side encryption" }, "end_to_end_encryption": { "type": "boolean", "example": false, "description": "Whether to use end-to-end encryption" }, "cloud_storage": { "type": "boolean", "example": false, "description": "Whether to use cloud storage feature" } } } } }, "page_size": { "type": "number", "description": "The amount of records returned in this response", "minimum": 1, "maximum": 100, "default": 10, "example": 10 }, "user_lite": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/user_id" }, "name": { "$ref": "#/components/schemas/user_name" }, "display_name": { "$ref": "#/components/schemas/user_display_name" }, "_links": { "$ref": "#/components/schemas/user_links" } } }, "user_id": { "type": "string", "example": "USR-82e028d9-5201-4f1e-8188-604b2d3471ec", "description": "User ID" }, "user_name": { "type": "string", "example": "my_user_name", "description": "Unique name for a user" }, "user_display_name": { "type": "string", "example": "My User Name", "description": "A string to be displayed as user name. It does not need to be unique" }, "user_links": { "type": "object", "properties": { "self": { "type": "object", "properties": { "href": { "type": "string", "example": "https://api.nexmo.com/v1/users/USR-82e028d9-5201-4f1e-8188-604b2d3471ec" } } } } }, "user_image_url": { "type": "string", "example": "https://example.com/image.png", "description": "An image URL that you associate with the user" }, "user_properties": { "type": "object", "description": "User properties", "properties": { "custom_data": { "type": "object", "description": "custom key/value pairs", "example": { "custom_key": "custom_value" } }, "ttl": { "type": "integer", "description": "Time to live in seconds", "example": 3600, "maximum": 2147483648 } } }, "user_channels": { "type": "object", "properties": { "pstn": { "type": "array", "items": { "type": "object", "properties": { "number": { "type": "integer", "example": 123457 } } } }, "sip": { "type": "array", "items": { "type": "object", "properties": { "uri": { "type": "string", "example": "sip:4442138907@sip.example.com;transport=tls", "description": "Value must match regular expression ^(sip|sips):\\\\+?([\\\\w|:.\\\\-@;,=%&]+)" }, "username": { "type": "string", "example": "New SIP" }, "password": { "type": "string", "example": "Password" } } } }, "vbc": { "type": "array", "items": { "type": "object", "properties": { "extension": { "type": "string", "example": "403" } } } }, "websocket": { "type": "array", "items": { "type": "object", "properties": { "uri": { "type": "string", "description": "Value must match regular expression ^(ws|wss):\\/\\/[a-zA-Z0-9~#%@&-_?\\\\/.,:;)(\\]\\[]*$", "example": "wss://example.com/socket" }, "content-type": { "type": "string", "example": "audio/l16;rate=16000", "enum": [ "audio/l16;rate=8000", "audio/l16;rate=16000" ] }, "headers": { "description": "Details of the Websocket to connect to", "type": "object", "properties": { "customer_id": { "type": "string", "example": "ABC123", "description": "This is an example header. You can provide any headers you may need" } } } } } }, "sms": { "type": "array", "items": { "type": "object", "properties": { "number": { "type": "string", "example": "447700900000" } } } }, "mms": { "type": "array", "items": { "type": "object", "properties": { "number": { "type": "string", "example": "447700900000" } } } }, "whatsapp": { "type": "array", "items": { "type": "object", "properties": { "number": { "type": "string", "example": "447700900000" } } } }, "viber": { "type": "array", "items": { "type": "object", "properties": { "number": { "type": "string", "example": "447700900000" } } } }, "messenger": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "example": "12345abcd" } } } } } }, "user": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/user_id" }, "name": { "$ref": "#/components/schemas/user_name" }, "display_name": { "$ref": "#/components/schemas/user_display_name" }, "image_url": { "$ref": "#/components/schemas/user_image_url" }, "properties": { "$ref": "#/components/schemas/user_properties" }, "channels": { "$ref": "#/components/schemas/user_channels" }, "_links": { "$ref": "#/components/schemas/user_links" } } }, "active_webhook": { "type": "boolean", "example": true, "description": "Whether the webhook is active" }, "instance": { "description": "Instance ID", "type": "string", "example": "797a8f199c45014ab7b08bfe9cc1c12c" } }, "parameters": { "page_size": { "name": "page_size", "in": "query", "description": "Return this amount of records in the response", "required": false, "schema": { "$ref": "#/components/schemas/page_size" } }, "order": { "name": "order", "in": "query", "description": "Return the records in ascending or descending order.", "required": false, "schema": { "type": "string", "default": "asc", "enum": [ "asc", "desc", "ASC", "DESC" ] } }, "cursor": { "name": "cursor", "in": "query", "description": "The cursor to start returning results from.\n\nYou are not expected to provide this manually, but to follow the url provided in `_links.next.href` or `_links.prev.href` in the response which contains a `cursor` value.\n", "schema": { "type": "string" }, "required": false }, "user_id": { "name": "id", "in": "path", "required": true, "description": "Unique ID for a user", "schema": { "$ref": "#/components/schemas/user_id" } }, "user_name": { "name": "name", "in": "query", "required": false, "description": "Unique name for a user", "schema": { "$ref": "#/components/schemas/user_name" } }, "user_id_name": { "name": "id | name", "in": "path", "required": true, "description": "Unique ID or name for a user", "schema": { "$ref": "#/components/schemas/user_id" } } } }, "x-errors": { "payload-validation": { "description": "Invalid request. See `invalid_parameters` field for details", "resolution": "Review the documentation and send a valid `POST` request.", "link": { "text": "View API reference", "url": "/api/application.v2#createApplication" } }, "list-validation": { "description": "Invalid request. See `invalid_parameters` field for details", "resolution": "Review the documentation and send a valid `GET` request.", "link": { "text": "View API reference", "url": "/api/application.v2#listApplication" } }, "rate-limit": { "description": "The request was rate limited", "resolution": "The Redact API supports 170 requests per second. Reduce the frequency of your requests." } }, "tags": [ { "name": "Application", "description": "A Vonage API application contains the security and configuration information you need to connect to Vonage endpoints and use the Vonage APIs." }, { "name": "User", "description": "The concept of a user exists in Vonage APIs, you can associate one with a user in your own application if you choose. A user can have multiple memberships to conversations and can communicate with other users through various different mediums." } ] }