Skip to content
Permalink
main
Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?
Go to file
 
 
Cannot retrieve contributors at this time
---
openapi: "3.0.0"
info:
version: 2.1.4
title: "Application API"
description: |
Vonage provides an Application API to allow management of your Vonage 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.
contact:
name: Vonage
url: "https://developer.nexmo.com/"
email: devrel@nexmo.com
servers:
- url: https://api.nexmo.com/v2/applications
security:
- basicAuth: []
paths:
/:
get:
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.nexmo.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: "common/common_errors.yml#/components/schemas/instance"
"401":
$ref: "common/common_errors.yml#/components/responses/BadCredentialsError"
"405":
$ref: "common/common_errors.yml#/components/responses/InvalidRequestMethod"
"406":
$ref: "common/common_errors.yml#/components/responses/InvalidAcceptHeader"
post:
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-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCA
KOxjsU4pf/sMFi9N0jqcSLcjxu33G
d/vynKnlw9SENi+UZR44GdjGdmfm1
tL1eA7IBh2HNnkYXnAwYzKJoa4eO3
0kYWekeIZawIwe/g9faFgkev+1xsO
OUNhPx2LhuLmgwWSRS4L5W851Xe3f
UQIDAQAB
-----END PUBLIC KEY-----
description: Public key
capabilities:
$ref: '#/components/schemas/capabilities'
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-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCA
KOxjsU4pf/sMFi9N0jqcSLcjxu33G
d/vynKnlw9SENi+UZR44GdjGdmfm1
tL1eA7IBh2HNnkYXnAwYzKJoa4eO3
0kYWekeIZawIwe/g9faFgkev+1xsO
OUNhPx2LhuLmgwWSRS4L5W851Xe3f
UQIDAQAB
-----END PUBLIC KEY-----
private_key:
type: string
example: |
-----BEGIN PRIVATE KEY-----
MIIEvQIBADANBgkqhkiG9w0BAQEFA
ASCBKcwggSjAgEAAoIBAQDEPpvi+3
RH1efQ\nkveWzZDrNNoEXmBw61w+O
0u/N36tJnN5XnYecU64yHzu2ByEr0
7iIvYbavFnADwl\nHMTJwqDQakpa3
8/SFRnTDq3zronvNZ6nOp7S6K7pcZ
rw/CvrL6hXT1x7cGBZ4jPx\nqhjqY
uJPgZD7OVB69oYOV92vIIJ7JLYwqb
-----END PRIVATE KEY-----
"400":
$ref: "#/components/responses/InvalidPayloadError"
"401":
$ref: "common/common_errors.yml#/components/responses/BadCredentialsError"
"405":
$ref: "common/common_errors.yml#/components/responses/InvalidRequestMethod"
"406":
$ref: "common/common_errors.yml#/components/responses/InvalidAcceptHeader"
"415":
$ref: "common/common_errors.yml#/components/responses/UnsupportedContentTypeHeader"
/{id}:
parameters:
- name: id
in: path
required: true
description: The ID of the application
example: 78d335fa-323d-0114-9c3d-d6f0d48968cf
schema:
type: string
get:
operationId: getApplication
summary: Get an application
responses:
"200":
description: Success
content:
application/json:
schema:
$ref: "#/components/schemas/ApplicationResponse"
"401":
$ref: "common/common_errors.yml#/components/responses/BadCredentialsError"
"404":
$ref: "common/common_errors.yml#/components/responses/NotFoundError"
"405":
$ref: "common/common_errors.yml#/components/responses/InvalidRequestMethod"
"406":
$ref: "common/common_errors.yml#/components/responses/InvalidAcceptHeader"
put:
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-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCA
KOxjsU4pf/sMFi9N0jqcSLcjxu33G
d/vynKnlw9SENi+UZR44GdjGdmfm1
tL1eA7IBh2HNnkYXnAwYzKJoa4eO3
0kYWekeIZawIwe/g9faFgkev+1xsO
OUNhPx2LhuLmgwWSRS4L5W851Xe3f
UQIDAQAB
-----END PUBLIC KEY-----
description: Public key
capabilities:
$ref: '#/components/schemas/capabilities'
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-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCA
KOxjsU4pf/sMFi9N0jqcSLcjxu33G
d/vynKnlw9SENi+UZR44GdjGdmfm1
tL1eA7IBh2HNnkYXnAwYzKJoa4eO3
0kYWekeIZawIwe/g9faFgkev+1xsO
OUNhPx2LhuLmgwWSRS4L5W851Xe3f
UQIDAQAB
-----END PUBLIC KEY-----
private_key:
type: string
example: |
-----BEGIN PRIVATE KEY-----
MIIEvQIBADANBgkqhkiG9w0BAQEFA
ASCBKcwggSjAgEAAoIBAQDEPpvi+3
RH1efQ\nkveWzZDrNNoEXmBw61w+O
0u/N36tJnN5XnYecU64yHzu2ByEr0
7iIvYbavFnADwl\nHMTJwqDQakpa3
8/SFRnTDq3zronvNZ6nOp7S6K7pcZ
rw/CvrL6hXT1x7cGBZ4jPx\nqhjqY
uJPgZD7OVB69oYOV92vIIJ7JLYwqb
-----END PRIVATE KEY-----
"400":
$ref: "#/components/responses/InvalidPayloadError"
"401":
$ref: "common/common_errors.yml#/components/responses/BadCredentialsError"
"404":
$ref: "common/common_errors.yml#/components/responses/NotFoundError"
"405":
$ref: "common/common_errors.yml#/components/responses/InvalidRequestMethod"
"406":
$ref: "common/common_errors.yml#/components/responses/InvalidAcceptHeader"
"415":
$ref: "common/common_errors.yml#/components/responses/UnsupportedContentTypeHeader"
delete:
operationId: deleteApplication
summary: Delete an application
description: Deleting an application **cannot be undone**.
responses:
"204":
description: Success
"401":
$ref: "common/common_errors.yml#/components/responses/BadCredentialsError"
"404":
$ref: "common/common_errors.yml#/components/responses/NotFoundError"
"405":
$ref: "common/common_errors.yml#/components/responses/InvalidRequestMethod"
"406":
$ref: "common/common_errors.yml#/components/responses/InvalidAcceptHeader"
components:
securitySchemes:
basicAuth:
type: http
scheme: basic
responses:
InvalidPayloadError:
description: Invalid Request
content:
application/json:
schema:
properties:
type:
type: string
example: "https://developer.nexmo.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: "common/common_errors.yml#/components/schemas/instance"
schemas:
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:
$ref: '#/components/schemas/capabilities'
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
capabilities:
type: object
properties:
messages:
$ref: '#/components/schemas/MessagesCapability'
rtc:
$ref: '#/components/schemas/RtcCapability'
voice:
$ref: '#/components/schemas/VoiceCapability'
meetings:
$ref: '#/components/schemas/MeetingsCapability'
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.
verify:
$ref: '#/components/schemas/VerifyCapability'
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.
MessagesCapability:
type: object
description: Messages / Dispatch related configuration
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
RtcCapability:
type: object
description: RTC / Conversation Service related configuration
properties:
signed_callbacks:
type: boolean
example: true
leg_persistence_time:
maximum: 31
minimum: 1
type: integer
format: int32
example: 5
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
VoiceCapability:
type: object
description: Voice related configuration
properties:
signed_callbacks:
type: boolean
description: "verify that a request is coming from Vonage servers (a jwt token will be sent on the callback authorization header)"
example: true
conversation_ttl:
type: integer
description: "ttl used by the NCCO in case you’re using a conversation action (is set in hours and is 48 by default)"
example: 30
payments:
type: object
description: "encompass all the payment related fields"
properties:
gateways:
type: array
description: "payment gateways like Stripe"
items:
type: object
properties:
type:
type: string
description: "payment gateway type (Stripe, Azure)"
example: Stripe
credential:
type: string
description: "used to identify the gateway in the credentials service"
example: 26f2a89e-6fcd-11ed-a1eb-0242ac120002
mode:
type: string
description: "determines if the user has completed the integration with the gateway"
example: live
enum:
- test
- live
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
enum:
- GET
- POST
description: The HTTP method used to fetch your NCCO from your `answer_url`
connection_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
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
`fallback_answer_url` if it is set. This URL must return an NCCO.
http_method:
type: string
example: POST
enum:
- GET
- POST
description: The HTTP method used to fetch your NCCO from your `answer_url`
connection_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"
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
enum:
- GET
- POST
description: The HTTP method used to send events to your server
connection_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
MeetingsCapability:
type: object
description: Meetings related configuration
properties:
webhooks:
type: object
properties:
room_changed:
type: object
description: "Vonage will send call room changed events to this URL"
properties:
address:
type: string
example: https://example.com/webhooks/event
http_method:
type: string
example: POST
enum:
- GET
- POST
- PUT
session_changed:
type: object
description: "Vonage will send call session changed events to this URL"
properties:
address:
type: string
example: https://example.com/webhooks/event
http_method:
type: string
example: POST
enum:
- GET
- POST
- PUT
recording_changed:
type: object
description: "Vonage will send recording changed events to this URL"
properties:
address:
type: string
example: https://example.com/webhooks/event
http_method:
type: string
example: POST
enum:
- GET
- POST
- PUT
VerifyCapability:
type: object
description: Two factor authentication related configuration
properties:
webhooks:
type: object
properties:
status_url:
type: object
description: "Vonage will send request status events (e.g. `progress`, `complete`) to this URL"
properties:
address:
type: string
example: https://example.com/webhooks/event
http_method:
type: string
example: POST
enum:
- POST
version:
type: string
description: Verify current version. If specified must be set to v2
example: v2
enum:
- v2
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.