Application API

Version 2

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.

Download OpenAPI Specification

Application

A Vonage API application contains the security and configuration information you need to connect to Vonage endpoints and use the Vonage APIs.

Available Operations

List available applications

gethttps://api.nexmo.com/v2/applications

Authentication

Key	Description	Where	Example
Authorization	Base64 encoded API key and secret joined by a colon. Read more	Headers	`Basic <base64>`

Query Parameters

page_size

integer

The number of applications per page

page

integer

The current page number (starts at 1)

Responses
Content Type
application/json

Success

page_size

integer

example10

The number of applications per page

page

integer

example1

The current page number (starts at 1)

total_items

integer

example6

The total number of applications

total_pages

integer

example1

The total number of pages returned

_embedded

object

A list of applications matching your existing filters

applications

array

string

example78d335fa-323d-0114-9c3d-d6f0d48968cf

The application's ID

name

string

exampleMy Application

Friendly identifier for your application. This is not unique

capabilities

object

Configuration for the products available in this application

voice

object

Voice related configuration

webhooks

object

answer_url

object

address

string

examplehttps://example.com/webhooks/answer

The URL that Vonage requests when a call is placed/received. Must return an NCCO

http_method

string

examplePOST

The HTTP method used to fetch your NCCO from your answer_url

connection_timeout

integer

example500

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.

socket_timeout

integer

example3000

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.

fallback_answer_url

object

address

string

examplehttps://fallback.example.com/webhooks/answer

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

string

examplePOST

The HTTP method used to fetch your NCCO from your answer_url

connection_timeout

integer

example500

Connection timeout in milliseconds

socket_timeout

integer

example3000

Reading timeout in milliseconds

event_url

object

address

string

examplehttps://example.com/webhooks/event

The URL that Vonage sends events related to your call to

http_method

string

examplePOST

The HTTP method used to send events to your server

connection_timeout

integer

example500

socket_timeout

integer

example3000

signed_callbacks

boolean

Defaulttrue

Whether to use signed webhooks. This is a way of verifying that the request is coming from Vonage. Refer to the Webhooks documentation for more information.

conversations_ttl

integer

Min1

Max9000

Default48

example12

The length of time named conversations will remain active for after creation, in hours. Maximum value is 9000 (i.e. 365 days).

leg_persistence_time

integer

Min1

Max31

Default2

example10

The persistence duration for legs, in days. Maximum value is 31.

region

string

exampleeu-west

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.

Must be one of:na-eastna-westeu-easteu-westapac-sngapac-australia

messages

object

Messages / Dispatch related configuration

webhooks

object

inbound_url

object

address

string

examplehttps://example.com/webhooks/inbound

The URL that Vonage forwards inbound messages to on your server

http_method

string

examplePOST

The HTTP method used to send inbound messages to your server

status_url

object

address

string

examplehttps://example.com/webhooks/status

The URL that Vonage sends events related to your messages to

http_method

string

examplePOST

The HTTP method used to send events to your server (always POST)

rtc

object

RTC / Conversation Service related configuration

webhooks

object

event_url

object

address

string

examplehttps://example.com/webhooks/event

http_method

string

examplePOST

signed_callbacks

boolean

Defaulttrue

Whether to use signed webhooks. This is a way of verifying that the request is coming from Vonage. Refer to the Webhooks documentation for more information.

vbc

object

Specify the vbc capability to enable zero-rated calls for VBC number programmability service applications. This is always an empty object.

network_apis

object

Network APIs

network_application_id

string

example2bzfIFqRG128IcjSj1YhZNtw6LADG

redirect_uri

string

examplehttps://my-redirect-uri.example.com

meetings

object

Meetings related configuration

webhooks

object

recording_changed

object

address

string

examplehttps://example.com/webhooks/recordings

The URL that Vonage forwards recording information to on your server

http_method

string

examplePOST

The HTTP method used to send recording information to your server (always POST)

room_changed

object

address

string

examplehttps://example.com/webhooks/rooms

The URL that Vonage forwards meeting room information on your server.

http_method

string

examplePOST

The HTTP method used to send meeting room information to your server (always POST)

session_changed

object

address

string

examplehttps://example.com/webhooks/sessions

The URL that Vonage forwards session information on your server.

http_method

string

examplePOST

The HTTP method used to send session information to your server (always POST)

verify

object

Verify v2 related configuration

version

string

examplev2

The version of the Verify API to use

webhooks

object

status_url

object

address

string

examplehttps://example.com/webhooks/status

The URL that Vonage sends events related to your verify requests to

http_method

string

examplePOST

The HTTP method used to send events to your server (always POST)

privacy

object

Application privacy config

improve_ai

boolean

exampletrue

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 Response

{
   "page_size": 10,
   "page": 1,
   "total_items": 6,
   "total_pages": 1,
   "_embedded": {
      "applications": [
         {
            "id": "78d335fa-323d-0114-9c3d-d6f0d48968cf",
            "name": "My Application",
            "capabilities": {
               "voice": {
                  "webhooks": {
                     "answer_url": {
                        "address": "https://example.com/webhooks/answer",
                        "http_method": "POST",
                        "connection_timeout": 500,
                        "socket_timeout": 3000
                     },
                     "fallback_answer_url": {
                        "address": "https://fallback.example.com/webhooks/answer",
                        "http_method": "POST",
                        "connection_timeout": 500,
                        "socket_timeout": 3000
                     },
                     "event_url": {
                        "address": "https://example.com/webhooks/event",
                        "http_method": "POST",
                        "connection_timeout": 500,
                        "socket_timeout": 3000
                     }
                  },
                  "signed_callbacks": false,
                  "conversations_ttl": 12,
                  "leg_persistence_time": 10,
                  "region": "eu-west"
               },
               "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"
                     }
                  },
                  "signed_callbacks": false
               },
               "vbc": {},
               "network_apis": {
                  "network_application_id": "2bzfIFqRG128IcjSj1YhZNtw6LADG",
                  "redirect_uri": "https://my-redirect-uri.example.com"
               },
               "meetings": {
                  "webhooks": {
                     "recording_changed": {
                        "address": "https://example.com/webhooks/recordings",
                        "http_method": "POST"
                     },
                     "room_changed": {
                        "address": "https://example.com/webhooks/rooms",
                        "http_method": "POST"
                     },
                     "session_changed": {
                        "address": "https://example.com/webhooks/sessions",
                        "http_method": "POST"
                     }
                  }
               },
               "verify": {
                  "version": "v2",
                  "webhooks": {
                     "status_url": {
                        "address": "https://example.com/webhooks/status",
                        "http_method": "POST"
                     }
                  }
               }
            },
            "privacy": {
               "improve_ai": true
            }
         }
      ]
   }
}

Create an application

posthttps://api.nexmo.com/v2/applications

Authentication

Key	Description	Where	Example
Authorization	Base64 encoded API key and secret joined by a colon. Read more	Headers	`Basic <base64>`

Request Body
Content Type
application/json

name

string

Required

exampleDemo Application

Application Name

keys

object

public_key

string

example

Public key

capabilities

object

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

object

Voice application webhook config

webhooks

object

answer_url

object

The URL that Vonage makes a request to when a call is placed/received. Must return an NCCO

address

string

examplehttps://example.com/webhooks/answer

http_method

string

exampleGET

Must be one of:GETPOST

connection_timeout

integer

Min300

Max1000

Default1000

example500

socket_timeout

integer

Min1000

Max5000

Default5000

example3000

fallback_answer_url

object

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.

address

string

examplehttps://fallback.example.com/webhooks/answer

http_method

string

exampleGET

Must be one of:GETPOST

connection_timeout

integer

Min300

Max1000

Default1000

example500

socket_timeout

integer

Min1000

Max5000

Default5000

example3000

event_url

object

Vonage will send call events (e.g. ringing, answered) to this URL

address

string

examplehttps://example.com/webhooks/event

http_method

string

examplePOST

Must be one of:GETPOST

connection_timeout

integer

Min300

Max1000

Default1000

example500

socket_timeout

integer

Min1000

Max10000

Default10000

example3000

signed_callbacks

boolean

Defaulttrue

Whether to use signed webhooks. This is a way of verifying that the request is coming from Vonage. Refer to the Webhooks documentation for more information.

conversations_ttl

integer

Min1

Max9000

Default48

example12

The length of time named conversations will remain active for after creation, in hours. Maximum value is 9000 (i.e. 365 days).

leg_persistence_time

integer

Min1

Max31

Default2

example10

The persistence duration for legs, in days. Maximum value is 31.

region

string

exampleeu-west

Must be one of:na-eastna-westeu-easteu-westapac-sngapac-australia

rtc

object

RTC / Client SDK application webhook config

webhooks

object

event_url

object

Vonage will send RTC events to this URL

address

string

examplehttps://example.com/webhooks/event

http_method

string

examplePOST

Must be one of:GETPOST

signed_callbacks

boolean

Defaulttrue

Whether to use signed webhooks. This is a way of verifying that the request is coming from Vonage. Refer to the Webhooks documentation for more information.

messages

object

Messages and Dispatch application webhook config

version

string

If not populated will be set to v1

webhooks

object

inbound_url

object

Vonage will forward inbound messages to this URL

address

string

examplehttps://example.com/webhooks/inbound

http_method

string

examplePOST

Must be one of:POST

status_url

object

Vonage will send message status updates (e.g. delivered, seen) to this URL

address

string

examplehttps://example.com/webhooks/status

http_method

string

examplePOST

Must be one of:POST

vbc

object

Specify vbc capability to enable zero-rated calls for VBC number programmability service applications. This must be an empty object.

network_apis

object

Network APIs

network_application_id

string

example2bzfIFqRG128IcjSj1YhZNtw6LADG

redirect_uri

string

examplehttps://my-redirect-uri.example.com

meetings

object

Meetings related configuration

webhooks

object

recording_changed

object

The URL that Vonage forwards recording information to on your server

address

string

examplehttps://example.com/webhooks/recordings

http_method

string

examplePOST

Must be one of:POST

room_changed

object

The URL that Vonage forwards meeting room information on your server.

address

string

examplehttps://example.com/webhooks/rooms

http_method

string

examplePOST

Must be one of:POST

session_changed

object

The URL that Vonage forwards session information on your server.

address

string

examplehttps://example.com/webhooks/sessions

http_method

string

examplePOST

Must be one of:POST

verify

object

Verify v2 application webhook config

webhooks

object

status_url

object

Vonage will send Verify updates to this URL

address

string

examplehttps://example.com/webhooks/status

http_method

string

examplePOST

Must be one of:POST

privacy

object

Application privacy config

improve_ai

boolean

Defaulttrue

exampletrue

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 Request

{
   "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",
               "connection_timeout": 500,
               "socket_timeout": 3000
            },
            "fallback_answer_url": {
               "address": "https://fallback.example.com/webhooks/answer",
               "http_method": "GET",
               "connection_timeout": 500,
               "socket_timeout": 3000
            },
            "event_url": {
               "address": "https://example.com/webhooks/event",
               "http_method": "POST",
               "connection_timeout": 500,
               "socket_timeout": 3000
            }
         },
         "signed_callbacks": false,
         "conversations_ttl": 12,
         "leg_persistence_time": 10,
         "region": "eu-west"
      },
      "rtc": {
         "webhooks": {
            "event_url": {
               "address": "https://example.com/webhooks/event",
               "http_method": "POST"
            }
         },
         "signed_callbacks": false
      },
      "messages": {
         "version": "string",
         "webhooks": {
            "inbound_url": {
               "address": "https://example.com/webhooks/inbound",
               "http_method": "POST"
            },
            "status_url": {
               "address": "https://example.com/webhooks/status",
               "http_method": "POST"
            }
         }
      },
      "vbc": {},
      "network_apis": {
         "network_application_id": "2bzfIFqRG128IcjSj1YhZNtw6LADG",
         "redirect_uri": "https://my-redirect-uri.example.com"
      },
      "meetings": {
         "webhooks": {
            "recording_changed": {
               "address": "https://example.com/webhooks/recordings",
               "http_method": "POST"
            },
            "room_changed": {
               "address": "https://example.com/webhooks/rooms",
               "http_method": "POST"
            },
            "session_changed": {
               "address": "https://example.com/webhooks/sessions",
               "http_method": "POST"
            }
         }
      },
      "verify": {
         "webhooks": {
            "status_url": {
               "address": "https://example.com/webhooks/status",
               "http_method": "POST"
            }
         }
      }
   },
   "privacy": {
      "improve_ai": true
   }
}

{
   "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",
               "connection_timeout": 500,
               "socket_timeout": 3000
            },
            "fallback_answer_url": {
               "address": "https://fallback.example.com/webhooks/answer",
               "http_method": "GET",
               "connection_timeout": 500,
               "socket_timeout": 3000
            },
            "event_url": {
               "address": "https://example.com/webhooks/event",
               "http_method": "POST",
               "connection_timeout": 500,
               "socket_timeout": 3000
            }
         },
         "signed_callbacks": false,
         "conversations_ttl": 12,
         "leg_persistence_time": 10,
         "region": "eu-west"
      },
      "rtc": {
         "webhooks": {
            "event_url": {
               "address": "https://example.com/webhooks/event",
               "http_method": "POST"
            }
         },
         "signed_callbacks": false
      },
      "messages": {
         "version": "string",
         "webhooks": {
            "inbound_url": {
               "address": "https://example.com/webhooks/inbound",
               "http_method": "POST"
            },
            "status_url": {
               "address": "https://example.com/webhooks/status",
               "http_method": "POST"
            }
         }
      },
      "vbc": {},
      "network_apis": {
         "network_application_id": "2bzfIFqRG128IcjSj1YhZNtw6LADG",
         "redirect_uri": "https://my-redirect-uri.example.com"
      },
      "meetings": {
         "webhooks": {
            "recording_changed": {
               "address": "https://example.com/webhooks/recordings",
               "http_method": "POST"
            },
            "room_changed": {
               "address": "https://example.com/webhooks/rooms",
               "http_method": "POST"
            },
            "session_changed": {
               "address": "https://example.com/webhooks/sessions",
               "http_method": "POST"
            }
         }
      },
      "verify": {
         "webhooks": {
            "status_url": {
               "address": "https://example.com/webhooks/status",
               "http_method": "POST"
            }
         }
      }
   },
   "privacy": {
      "improve_ai": true
   }
}

Responses
Content Type
application/json

Success

string

example78d335fa-323d-0114-9c3d-d6f0d48968cf

The application's ID

name

string

exampleMy Application

Friendly identifier for your application. This is not unique

capabilities

object

Configuration for the products available in this application

voice

object

Voice related configuration

webhooks

object

answer_url

object

address

string

examplehttps://example.com/webhooks/answer

The URL that Vonage requests when a call is placed/received. Must return an NCCO

http_method

string

examplePOST

The HTTP method used to fetch your NCCO from your answer_url

connection_timeout

integer

example500

socket_timeout

integer

example3000

fallback_answer_url

object

address

string

examplehttps://fallback.example.com/webhooks/answer

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

string

examplePOST

The HTTP method used to fetch your NCCO from your answer_url

connection_timeout

integer

example500

Connection timeout in milliseconds

socket_timeout

integer

example3000

Reading timeout in milliseconds

event_url

object

address

string

examplehttps://example.com/webhooks/event

The URL that Vonage sends events related to your call to

http_method

string

examplePOST

The HTTP method used to send events to your server

connection_timeout

integer

example500

socket_timeout

integer

example3000

signed_callbacks

boolean

Defaulttrue

Whether to use signed webhooks. This is a way of verifying that the request is coming from Vonage. Refer to the Webhooks documentation for more information.

conversations_ttl

integer

Min1

Max9000

Default48

example12

The length of time named conversations will remain active for after creation, in hours. Maximum value is 9000 (i.e. 365 days).

leg_persistence_time

integer

Min1

Max31

Default2

example10

The persistence duration for legs, in days. Maximum value is 31.

region

string

exampleeu-west

Must be one of:na-eastna-westeu-easteu-westapac-sngapac-australia

messages

object

Messages / Dispatch related configuration

webhooks

object

inbound_url

object

address

string

examplehttps://example.com/webhooks/inbound

The URL that Vonage forwards inbound messages to on your server

http_method

string

examplePOST

The HTTP method used to send inbound messages to your server

status_url

object

address

string

examplehttps://example.com/webhooks/status

The URL that Vonage sends events related to your messages to

http_method

string

examplePOST

The HTTP method used to send events to your server (always POST)

rtc

object

RTC / Conversation Service related configuration

webhooks

object

event_url

object

address

string

examplehttps://example.com/webhooks/event

http_method

string

examplePOST

signed_callbacks

boolean

Defaulttrue

Whether to use signed webhooks. This is a way of verifying that the request is coming from Vonage. Refer to the Webhooks documentation for more information.

vbc

object

Specify the vbc capability to enable zero-rated calls for VBC number programmability service applications. This is always an empty object.

network_apis

object

Network APIs

network_application_id

string

example2bzfIFqRG128IcjSj1YhZNtw6LADG

redirect_uri

string

examplehttps://my-redirect-uri.example.com

meetings

object

Meetings related configuration

webhooks

object

recording_changed

object

address

string

examplehttps://example.com/webhooks/recordings

The URL that Vonage forwards recording information to on your server

http_method

string

examplePOST

The HTTP method used to send recording information to your server (always POST)

room_changed

object

address

string

examplehttps://example.com/webhooks/rooms

The URL that Vonage forwards meeting room information on your server.

http_method

string

examplePOST

The HTTP method used to send meeting room information to your server (always POST)

session_changed

object

address

string

examplehttps://example.com/webhooks/sessions

The URL that Vonage forwards session information on your server.

http_method

string

examplePOST

The HTTP method used to send session information to your server (always POST)

verify

object

Verify v2 related configuration

version

string

examplev2

The version of the Verify API to use

webhooks

object

status_url

object

address

string

examplehttps://example.com/webhooks/status

The URL that Vonage sends events related to your verify requests to

http_method

string

examplePOST

The HTTP method used to send events to your server (always POST)

privacy

object

Application privacy config

improve_ai

boolean

exampletrue

If set to true, Vonage may store and use your content and data for the improvement of Vonage's AI based services and technologies.

keys

object

public_key

string

example

private_key

string

example

Example Response

{
   "id": "78d335fa-323d-0114-9c3d-d6f0d48968cf",
   "name": "My Application",
   "capabilities": {
      "voice": {
         "webhooks": {
            "answer_url": {
               "address": "https://example.com/webhooks/answer",
               "http_method": "POST",
               "connection_timeout": 500,
               "socket_timeout": 3000
            },
            "fallback_answer_url": {
               "address": "https://fallback.example.com/webhooks/answer",
               "http_method": "POST",
               "connection_timeout": 500,
               "socket_timeout": 3000
            },
            "event_url": {
               "address": "https://example.com/webhooks/event",
               "http_method": "POST",
               "connection_timeout": 500,
               "socket_timeout": 3000
            }
         },
         "signed_callbacks": false,
         "conversations_ttl": 12,
         "leg_persistence_time": 10,
         "region": "eu-west"
      },
      "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"
            }
         },
         "signed_callbacks": false
      },
      "vbc": {},
      "network_apis": {
         "network_application_id": "2bzfIFqRG128IcjSj1YhZNtw6LADG",
         "redirect_uri": "https://my-redirect-uri.example.com"
      },
      "meetings": {
         "webhooks": {
            "recording_changed": {
               "address": "https://example.com/webhooks/recordings",
               "http_method": "POST"
            },
            "room_changed": {
               "address": "https://example.com/webhooks/rooms",
               "http_method": "POST"
            },
            "session_changed": {
               "address": "https://example.com/webhooks/sessions",
               "http_method": "POST"
            }
         }
      },
      "verify": {
         "version": "v2",
         "webhooks": {
            "status_url": {
               "address": "https://example.com/webhooks/status",
               "http_method": "POST"
            }
         }
      }
   },
   "privacy": {
      "improve_ai": true
   },
   "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"
   }
}

Get an application

gethttps://api.nexmo.com/v2/applications/:id

Authentication

Key	Description	Where	Example
Authorization	Base64 encoded API key and secret joined by a colon. Read more	Headers	`Basic <base64>`

Path Parameters

string

Required

The ID of the application

Responses
Content Type
application/json

Success

string

example78d335fa-323d-0114-9c3d-d6f0d48968cf

The application's ID

name

string

exampleMy Application

Friendly identifier for your application. This is not unique

capabilities

object

Configuration for the products available in this application

voice

object

Voice related configuration

webhooks

object

answer_url

object

address

string

examplehttps://example.com/webhooks/answer

The URL that Vonage requests when a call is placed/received. Must return an NCCO

http_method

string

examplePOST

The HTTP method used to fetch your NCCO from your answer_url

connection_timeout

integer

example500

socket_timeout

integer

example3000

fallback_answer_url

object

address

string

examplehttps://fallback.example.com/webhooks/answer

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

string

examplePOST

The HTTP method used to fetch your NCCO from your answer_url

connection_timeout

integer

example500

Connection timeout in milliseconds

socket_timeout

integer

example3000

Reading timeout in milliseconds

event_url

object

address

string

examplehttps://example.com/webhooks/event

The URL that Vonage sends events related to your call to

http_method

string

examplePOST

The HTTP method used to send events to your server

connection_timeout

integer

example500

socket_timeout

integer

example3000

signed_callbacks

boolean

Defaulttrue

Whether to use signed webhooks. This is a way of verifying that the request is coming from Vonage. Refer to the Webhooks documentation for more information.

conversations_ttl

integer

Min1

Max9000

Default48

example12

The length of time named conversations will remain active for after creation, in hours. Maximum value is 9000 (i.e. 365 days).

leg_persistence_time

integer

Min1

Max31

Default2

example10

The persistence duration for legs, in days. Maximum value is 31.

region

string

exampleeu-west

Must be one of:na-eastna-westeu-easteu-westapac-sngapac-australia

messages

object

Messages / Dispatch related configuration

webhooks

object

inbound_url

object

address

string

examplehttps://example.com/webhooks/inbound

The URL that Vonage forwards inbound messages to on your server

http_method

string

examplePOST

The HTTP method used to send inbound messages to your server

status_url

object

address

string

examplehttps://example.com/webhooks/status

The URL that Vonage sends events related to your messages to

http_method

string

examplePOST

The HTTP method used to send events to your server (always POST)

rtc

object

RTC / Conversation Service related configuration

webhooks

object

event_url

object

address

string

examplehttps://example.com/webhooks/event

http_method

string

examplePOST

signed_callbacks

boolean

Defaulttrue

Whether to use signed webhooks. This is a way of verifying that the request is coming from Vonage. Refer to the Webhooks documentation for more information.

vbc

object

Specify the vbc capability to enable zero-rated calls for VBC number programmability service applications. This is always an empty object.

network_apis

object

Network APIs

network_application_id

string

example2bzfIFqRG128IcjSj1YhZNtw6LADG

redirect_uri

string

examplehttps://my-redirect-uri.example.com

meetings

object

Meetings related configuration

webhooks

object

recording_changed

object

address

string

examplehttps://example.com/webhooks/recordings

The URL that Vonage forwards recording information to on your server

http_method

string

examplePOST

The HTTP method used to send recording information to your server (always POST)

room_changed

object

address

string

examplehttps://example.com/webhooks/rooms

The URL that Vonage forwards meeting room information on your server.

http_method

string

examplePOST

The HTTP method used to send meeting room information to your server (always POST)

session_changed

object

address

string

examplehttps://example.com/webhooks/sessions

The URL that Vonage forwards session information on your server.

http_method

string

examplePOST

The HTTP method used to send session information to your server (always POST)

verify

object

Verify v2 related configuration

version

string

examplev2

The version of the Verify API to use

webhooks

object

status_url

object

address

string

examplehttps://example.com/webhooks/status

The URL that Vonage sends events related to your verify requests to

http_method

string

examplePOST

The HTTP method used to send events to your server (always POST)

privacy

object

Application privacy config

improve_ai

boolean

exampletrue

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 Response

{
   "id": "78d335fa-323d-0114-9c3d-d6f0d48968cf",
   "name": "My Application",
   "capabilities": {
      "voice": {
         "webhooks": {
            "answer_url": {
               "address": "https://example.com/webhooks/answer",
               "http_method": "POST",
               "connection_timeout": 500,
               "socket_timeout": 3000
            },
            "fallback_answer_url": {
               "address": "https://fallback.example.com/webhooks/answer",
               "http_method": "POST",
               "connection_timeout": 500,
               "socket_timeout": 3000
            },
            "event_url": {
               "address": "https://example.com/webhooks/event",
               "http_method": "POST",
               "connection_timeout": 500,
               "socket_timeout": 3000
            }
         },
         "signed_callbacks": false,
         "conversations_ttl": 12,
         "leg_persistence_time": 10,
         "region": "eu-west"
      },
      "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"
            }
         },
         "signed_callbacks": false
      },
      "vbc": {},
      "network_apis": {
         "network_application_id": "2bzfIFqRG128IcjSj1YhZNtw6LADG",
         "redirect_uri": "https://my-redirect-uri.example.com"
      },
      "meetings": {
         "webhooks": {
            "recording_changed": {
               "address": "https://example.com/webhooks/recordings",
               "http_method": "POST"
            },
            "room_changed": {
               "address": "https://example.com/webhooks/rooms",
               "http_method": "POST"
            },
            "session_changed": {
               "address": "https://example.com/webhooks/sessions",
               "http_method": "POST"
            }
         }
      },
      "verify": {
         "version": "v2",
         "webhooks": {
            "status_url": {
               "address": "https://example.com/webhooks/status",
               "http_method": "POST"
            }
         }
      }
   },
   "privacy": {
      "improve_ai": true
   }
}

Update an application

puthttps://api.nexmo.com/v2/applications/:id

Authentication

Key	Description	Where	Example
Authorization	Base64 encoded API key and secret joined by a colon. Read more	Headers	`Basic <base64>`

Path Parameters

string

Required

The ID of the application

Request Body
Content Type
application/json

name

string

Required

exampleDemo Application

Application Name

keys

object

public_key

string

example

Public key

capabilities

object

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

object

Voice application webhook config

webhooks

object

answer_url

object

The URL that Vonage make a request to when a call is placed/received. Must return an NCCO

address

string

examplehttps://example.com/webhooks/answer

http_method

string

exampleGET

Must be one of:GETPOST

connection_timeout

integer

Min300

Max1000

Default1000

example500

socket_timeout

integer

Min1000

Max5000

Default5000

example3000

fallback_answer_url

object

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

address

string

examplehttps://fallback.example.com/webhooks/answer

http_method

string

exampleGET

Must be one of:GETPOST

connection_timeout

integer

Min300

Max1000

Default1000

example500

socket_timeout

integer

Min1000

Max5000

Default5000

example3000

event_url

object

Vonage will send call events (e.g. ringing, answered) to this URL

address

string

examplehttps://example.com/webhooks/event

http_method

string

examplePOST

Must be one of:GETPOST

connection_timeout

integer

Min300

Max1000

Default1000

example500

socket_timeout

integer

Min1000

Max10000

Default10000

example3000

signed_callbacks

boolean

Defaulttrue

Whether to use signed webhooks. This is a way of verifying that the request is coming from Vonage. Refer to the Webhooks documentation for more information.

conversations_ttl

integer

Min1

Max9000

Default48

example12

The length of time named conversations will remain active for after creation, in hours. Maximum value is 9000 (i.e. 365 days).

leg_persistence_time

integer

Min1

Max31

Default2

example10

The persistence duration for legs, in days. Maximum value is 31.

region

string

exampleeu-west

Must be one of:na-eastna-westeu-easteu-westapac-sngapac-australia

rtc

object

RTC / Client SDK application webhook config

webhooks

object

event_url

object

Vonage will send RTC events to this URL

address

string

examplehttps://example.com/webhooks/event

http_method

string

examplePOST

Must be one of:GETPOST

signed_callbacks

boolean

Defaulttrue

Whether to use signed webhooks. This is a way of verifying that the request is coming from Vonage. Refer to the Webhooks documentation for more information.

messages

object

Messages and Dispatch application webhook config

webhooks

object

inbound_url

object

Vonage will forward inbound messages to this URL

address

string

examplehttps://example.com/webhooks/inbound

http_method

string

examplePOST

Must be one of:POST

status_url

object

Vonage will send message status updates (e.g. delivered, seen) to this URL

address

string

examplehttps://example.com/webhooks/status

http_method

string

examplePOST

Must be one of:POST

vbc

object

Specify the vbc capability to enable zero-rated calls for VBC number programmability service applications. This must be an empty object.

network_apis

object

Network APIs

network_application_id

string

example2bzfIFqRG128IcjSj1YhZNtw6LADG

redirect_uri

string

examplehttps://my-redirect-uri.example.com

meetings

object

Meetings related configuration

webhooks

object

recording_url

object

The URL that Vonage forwards recording information to on your server

address

string

examplehttps://example.com/webhooks/recordings

http_method

string

examplePOST

Must be one of:POST

rooms_url

object

The URL that Vonage forwards meeting room information on your server.

address

string

examplehttps://example.com/webhooks/rooms

http_method

string

examplePOST

Must be one of:POST

sessions_url

object

The URL that Vonage forwards session information on your server.

address

string

examplehttps://example.com/webhooks/sessions

http_method

string

examplePOST

Must be one of:POST

privacy

object

Application privacy config

improve_ai

boolean

exampletrue

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 Request

{
   "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",
               "connection_timeout": 500,
               "socket_timeout": 3000
            },
            "fallback_answer_url": {
               "address": "https://fallback.example.com/webhooks/answer",
               "http_method": "GET",
               "connection_timeout": 500,
               "socket_timeout": 3000
            },
            "event_url": {
               "address": "https://example.com/webhooks/event",
               "http_method": "POST",
               "connection_timeout": 500,
               "socket_timeout": 3000
            }
         },
         "signed_callbacks": false,
         "conversations_ttl": 12,
         "leg_persistence_time": 10,
         "region": "eu-west"
      },
      "rtc": {
         "webhooks": {
            "event_url": {
               "address": "https://example.com/webhooks/event",
               "http_method": "POST"
            }
         },
         "signed_callbacks": false
      },
      "messages": {
         "webhooks": {
            "inbound_url": {
               "address": "https://example.com/webhooks/inbound",
               "http_method": "POST"
            },
            "status_url": {
               "address": "https://example.com/webhooks/status",
               "http_method": "POST"
            }
         }
      },
      "vbc": {},
      "network_apis": {
         "network_application_id": "2bzfIFqRG128IcjSj1YhZNtw6LADG",
         "redirect_uri": "https://my-redirect-uri.example.com"
      },
      "meetings": {
         "webhooks": {
            "recording_url": {
               "address": "https://example.com/webhooks/recordings",
               "http_method": "POST"
            },
            "rooms_url": {
               "address": "https://example.com/webhooks/rooms",
               "http_method": "POST"
            },
            "sessions_url": {
               "address": "https://example.com/webhooks/sessions",
               "http_method": "POST"
            }
         }
      }
   },
   "privacy": {
      "improve_ai": true
   }
}

{
   "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",
               "connection_timeout": 500,
               "socket_timeout": 3000
            },
            "fallback_answer_url": {
               "address": "https://fallback.example.com/webhooks/answer",
               "http_method": "GET",
               "connection_timeout": 500,
               "socket_timeout": 3000
            },
            "event_url": {
               "address": "https://example.com/webhooks/event",
               "http_method": "POST",
               "connection_timeout": 500,
               "socket_timeout": 3000
            }
         },
         "signed_callbacks": false,
         "conversations_ttl": 12,
         "leg_persistence_time": 10,
         "region": "eu-west"
      },
      "rtc": {
         "webhooks": {
            "event_url": {
               "address": "https://example.com/webhooks/event",
               "http_method": "POST"
            }
         },
         "signed_callbacks": false
      },
      "messages": {
         "webhooks": {
            "inbound_url": {
               "address": "https://example.com/webhooks/inbound",
               "http_method": "POST"
            },
            "status_url": {
               "address": "https://example.com/webhooks/status",
               "http_method": "POST"
            }
         }
      },
      "vbc": {},
      "network_apis": {
         "network_application_id": "2bzfIFqRG128IcjSj1YhZNtw6LADG",
         "redirect_uri": "https://my-redirect-uri.example.com"
      },
      "meetings": {
         "webhooks": {
            "recording_url": {
               "address": "https://example.com/webhooks/recordings",
               "http_method": "POST"
            },
            "rooms_url": {
               "address": "https://example.com/webhooks/rooms",
               "http_method": "POST"
            },
            "sessions_url": {
               "address": "https://example.com/webhooks/sessions",
               "http_method": "POST"
            }
         }
      }
   },
   "privacy": {
      "improve_ai": true
   }
}

Responses
Content Type
application/json

Success

string

example78d335fa-323d-0114-9c3d-d6f0d48968cf

The application's ID

name

string

exampleMy Application

Friendly identifier for your application. This is not unique

capabilities

object

Configuration for the products available in this application

voice

object

Voice related configuration

webhooks

object

answer_url

object

address

string

examplehttps://example.com/webhooks/answer

The URL that Vonage requests when a call is placed/received. Must return an NCCO

http_method

string

examplePOST

The HTTP method used to fetch your NCCO from your answer_url

connection_timeout

integer

example500

socket_timeout

integer

example3000

fallback_answer_url

object

address

string

examplehttps://fallback.example.com/webhooks/answer

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

string

examplePOST

The HTTP method used to fetch your NCCO from your answer_url

connection_timeout

integer

example500

Connection timeout in milliseconds

socket_timeout

integer

example3000

Reading timeout in milliseconds

event_url

object

address

string

examplehttps://example.com/webhooks/event

The URL that Vonage sends events related to your call to

http_method

string

examplePOST

The HTTP method used to send events to your server

connection_timeout

integer

example500

socket_timeout

integer

example3000

signed_callbacks

boolean

Defaulttrue

Whether to use signed webhooks. This is a way of verifying that the request is coming from Vonage. Refer to the Webhooks documentation for more information.

conversations_ttl

integer

Min1

Max9000

Default48

example12

The length of time named conversations will remain active for after creation, in hours. Maximum value is 9000 (i.e. 365 days).

leg_persistence_time

integer

Min1

Max31

Default2

example10

The persistence duration for legs, in days. Maximum value is 31.

region

string

exampleeu-west

Must be one of:na-eastna-westeu-easteu-westapac-sngapac-australia

messages

object

Messages / Dispatch related configuration

webhooks

object

inbound_url

object

address

string

examplehttps://example.com/webhooks/inbound

The URL that Vonage forwards inbound messages to on your server

http_method

string

examplePOST

The HTTP method used to send inbound messages to your server

status_url

object

address

string

examplehttps://example.com/webhooks/status

The URL that Vonage sends events related to your messages to

http_method

string

examplePOST

The HTTP method used to send events to your server (always POST)

rtc

object

RTC / Conversation Service related configuration

webhooks

object

event_url

object

address

string

examplehttps://example.com/webhooks/event

http_method

string

examplePOST

signed_callbacks

boolean

Defaulttrue

Whether to use signed webhooks. This is a way of verifying that the request is coming from Vonage. Refer to the Webhooks documentation for more information.

vbc

object

Specify the vbc capability to enable zero-rated calls for VBC number programmability service applications. This is always an empty object.

network_apis

object

Network APIs

network_application_id

string

example2bzfIFqRG128IcjSj1YhZNtw6LADG

redirect_uri

string

examplehttps://my-redirect-uri.example.com

meetings

object

Meetings related configuration

webhooks

object

recording_changed

object

address

string

examplehttps://example.com/webhooks/recordings

The URL that Vonage forwards recording information to on your server

http_method

string

examplePOST

The HTTP method used to send recording information to your server (always POST)

room_changed

object

address

string

examplehttps://example.com/webhooks/rooms

The URL that Vonage forwards meeting room information on your server.

http_method

string

examplePOST

The HTTP method used to send meeting room information to your server (always POST)

session_changed

object

address

string

examplehttps://example.com/webhooks/sessions

The URL that Vonage forwards session information on your server.

http_method

string

examplePOST

The HTTP method used to send session information to your server (always POST)

verify

object

Verify v2 related configuration

version

string

examplev2

The version of the Verify API to use

webhooks

object

status_url

object

address

string

examplehttps://example.com/webhooks/status

The URL that Vonage sends events related to your verify requests to

http_method

string

examplePOST

The HTTP method used to send events to your server (always POST)

privacy

object

Application privacy config

improve_ai

boolean

exampletrue

If set to true, Vonage may store and use your content and data for the improvement of Vonage's AI based services and technologies.

keys

object

public_key

string

example

private_key

string

example

Example Response

{
   "id": "78d335fa-323d-0114-9c3d-d6f0d48968cf",
   "name": "My Application",
   "capabilities": {
      "voice": {
         "webhooks": {
            "answer_url": {
               "address": "https://example.com/webhooks/answer",
               "http_method": "POST",
               "connection_timeout": 500,
               "socket_timeout": 3000
            },
            "fallback_answer_url": {
               "address": "https://fallback.example.com/webhooks/answer",
               "http_method": "POST",
               "connection_timeout": 500,
               "socket_timeout": 3000
            },
            "event_url": {
               "address": "https://example.com/webhooks/event",
               "http_method": "POST",
               "connection_timeout": 500,
               "socket_timeout": 3000
            }
         },
         "signed_callbacks": false,
         "conversations_ttl": 12,
         "leg_persistence_time": 10,
         "region": "eu-west"
      },
      "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"
            }
         },
         "signed_callbacks": false
      },
      "vbc": {},
      "network_apis": {
         "network_application_id": "2bzfIFqRG128IcjSj1YhZNtw6LADG",
         "redirect_uri": "https://my-redirect-uri.example.com"
      },
      "meetings": {
         "webhooks": {
            "recording_changed": {
               "address": "https://example.com/webhooks/recordings",
               "http_method": "POST"
            },
            "room_changed": {
               "address": "https://example.com/webhooks/rooms",
               "http_method": "POST"
            },
            "session_changed": {
               "address": "https://example.com/webhooks/sessions",
               "http_method": "POST"
            }
         }
      },
      "verify": {
         "version": "v2",
         "webhooks": {
            "status_url": {
               "address": "https://example.com/webhooks/status",
               "http_method": "POST"
            }
         }
      }
   },
   "privacy": {
      "improve_ai": true
   },
   "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"
   }
}

Delete an application

Deleting an application cannot be undone.

deletehttps://api.nexmo.com/v2/applications/:id

Authentication

Key	Description	Where	Example
Authorization	Base64 encoded API key and secret joined by a colon. Read more	Headers	`Basic <base64>`

Path Parameters

string

Required

The ID of the application

Responses

Success

User

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.

Available Operations

List users

gethttps://api.nexmo.com/v1/users

Authentication

Key	Description	Where	Example
Authorization	Your JSON web token. Read more about JWTs	Headers	`Bearer <JWT>`

Query Parameters

page_size

number

Min1

Max100

Default10

example10

Return this amount of records in the response

order

string

Defaultasc

Return the records in ascending or descending order.

Must be one of:ascdescASCDESC

cursor

string

The cursor to start returning results from.

You 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.

name

string

examplemy_user_name

Unique name for a user

Responses
Content Type
application/json

List of users

page_size

number

Required

Min1

Max100

Default10

example10

The amount of records returned in this response

_embedded

object

Required

A list of user objects. See the get details of a specific user response fields for a description of the nested objects

users

array

Required

List of users matching the provided filter

string

exampleUSR-82e028d9-5201-4f1e-8188-604b2d3471ec

User ID

name

string

examplemy_user_name

Unique name for a user

display_name

string

exampleMy User Name

A string to be displayed as user name. It does not need to be unique

_links

object

self

object

href

string

examplehttps://api.nexmo.com/v1/users/USR-82e028d9-5201-4f1e-8188-604b2d3471ec

_links

object

Required

A series of links between resources in this API in the http://stateless.co/hal_specification.html.

first

object

Required

href

string

examplehttps://api.nexmo.com/v1/users?order=desc&page_size=10

self

object

Required

href

string

examplehttps://api.nexmo.com/v1/users?order=desc&page_size=10&cursor=7EjDNQrAcipmOnc0HCzpQRkhBULzY44ljGUX4lXKyUIVfiZay5pv9wg%3D

object

href

string

examplehttps://api.nexmo.com/v1/users?order=desc&page_size=10&cursor=7EjDNQrAcipmOnc0HCzpQRkhBULzY44ljGUX4lXKyUIVfiZay5pv9wg%3D

object

href

string

examplehttps://api.nexmo.com/v1/users?order=desc&page_size=10&cursor=7EjDNQrAcipmOnc0HCzpQRkhBULzY44ljGUX4lXKyUIVfiZay5pv9wg%3D

Example Response

{
   "page_size": 10,
   "_embedded": {
      "users": [
         {
            "id": "USR-82e028d9-5201-4f1e-8188-604b2d3471ec",
            "name": "my_user_name",
            "display_name": "My User Name",
            "_links": {
               "self": {
                  "href": "https://api.nexmo.com/v1/users/USR-82e028d9-5201-4f1e-8188-604b2d3471ec"
               }
            }
         }
      ]
   },
   "_links": {
      "first": {
         "href": "https://api.nexmo.com/v1/users?order=desc&page_size=10"
      },
      "self": {
         "href": "https://api.nexmo.com/v1/users?order=desc&page_size=10&cursor=7EjDNQrAcipmOnc0HCzpQRkhBULzY44ljGUX4lXKyUIVfiZay5pv9wg%3D"
      },
      "next": {
         "href": "https://api.nexmo.com/v1/users?order=desc&page_size=10&cursor=7EjDNQrAcipmOnc0HCzpQRkhBULzY44ljGUX4lXKyUIVfiZay5pv9wg%3D"
      },
      "prev": {
         "href": "https://api.nexmo.com/v1/users?order=desc&page_size=10&cursor=7EjDNQrAcipmOnc0HCzpQRkhBULzY44ljGUX4lXKyUIVfiZay5pv9wg%3D"
      }
   }
}

Create a user

Note: Users must be created with an admin JWT.

posthttps://api.nexmo.com/v1/users

Authentication

Key	Description	Where	Example
Authorization	Your JSON web token. Read more about JWTs	Headers	`Bearer <JWT>`

Request Body
Content Type
application/json

name

string

examplemy_user_name

Unique name for a user

display_name

string

exampleMy User Name

A string to be displayed as user name. It does not need to be unique

image_url

string

examplehttps://example.com/image.png

An image URL that you associate with the user

properties

object

User properties

custom_data

object

example

{
  "custom_key": "custom_value"
}

custom key/value pairs

ttl

integer

Max2147483648

example3600

Time to live in seconds

channels

object

pstn

array

number

integer

example123457

sip

array

uri

string

examplesip:4442138907@sip.example.com;transport=tls

Value must match regular expression ^(sip|sips):\+?([\w|:.\-@;,=%&]+)

username

string

exampleNew SIP

password

string

examplePassword

vbc

array

extension

string

example403

websocket

array

uri

string

examplewss://example.com/socket

Value must match regular expression ^(ws|wss)://[a-zA-Z0-9~#%@&-_?\/.,:;)(][]*$

content-type

string

exampleaudio/l16;rate=16000

Must be one of:audio/l16;rate=8000audio/l16;rate=16000

headers

object

Details of the Websocket to connect to

customer_id

string

exampleABC123

This is an example header. You can provide any headers you may need

sms

array

number

string

example447700900000

mms

array

number

string

example447700900000

array

number

string

example447700900000

viber

array

number

string

example447700900000

messenger

array

string

example12345abcd

Example Request

{
   "name": "my_user_name",
   "display_name": "My User Name",
   "image_url": "https://example.com/image.png",
   "properties": {
      "custom_data": {
         "custom_key": "custom_value"
      },
      "ttl": 3600
   },
   "channels": {
      "pstn": [
         {
            "number": 123457
         }
      ],
      "sip": [
         {
            "uri": "sip:4442138907@sip.example.com;transport=tls",
            "username": "New SIP",
            "password": "Password"
         }
      ],
      "vbc": [
         {
            "extension": "403"
         }
      ],
      "websocket": [
         {
            "uri": "wss://example.com/socket",
            "content-type": "audio/l16;rate=16000",
            "headers": {
               "customer_id": "ABC123"
            }
         }
      ],
      "sms": [
         {
            "number": "447700900000"
         }
      ],
      "mms": [
         {
            "number": "447700900000"
         }
      ],
      "whatsapp": [
         {
            "number": "447700900000"
         }
      ],
      "viber": [
         {
            "number": "447700900000"
         }
      ],
      "messenger": [
         {
            "id": "12345abcd"
         }
      ]
   }
}

{
   "name": "my_user_name",
   "display_name": "My User Name",
   "image_url": "https://example.com/image.png",
   "properties": {
      "custom_data": {
         "custom_key": "custom_value"
      },
      "ttl": 3600
   },
   "channels": {
      "pstn": [
         {
            "number": 123457
         }
      ],
      "sip": [
         {
            "uri": "sip:4442138907@sip.example.com;transport=tls",
            "username": "New SIP",
            "password": "Password"
         }
      ],
      "vbc": [
         {
            "extension": "403"
         }
      ],
      "websocket": [
         {
            "uri": "wss://example.com/socket",
            "content-type": "audio/l16;rate=16000",
            "headers": {
               "customer_id": "ABC123"
            }
         }
      ],
      "sms": [
         {
            "number": "447700900000"
         }
      ],
      "mms": [
         {
            "number": "447700900000"
         }
      ],
      "whatsapp": [
         {
            "number": "447700900000"
         }
      ],
      "viber": [
         {
            "number": "447700900000"
         }
      ],
      "messenger": [
         {
            "id": "12345abcd"
         }
      ]
   }
}

Responses
Content Type
application/json

Create a user response

string

exampleUSR-82e028d9-5201-4f1e-8188-604b2d3471ec

User ID

name

string

examplemy_user_name

Unique name for a user

display_name

string

exampleMy User Name

A string to be displayed as user name. It does not need to be unique

image_url

string

examplehttps://example.com/image.png

An image URL that you associate with the user

properties

object

User properties

custom_data

object

example

{
  "custom_key": "custom_value"
}

custom key/value pairs

ttl

integer

Max2147483648

example3600

Time to live in seconds

channels

object

pstn

array

number

integer

example123457

sip

array

uri

string

examplesip:4442138907@sip.example.com;transport=tls

Value must match regular expression ^(sip|sips):\+?([\w|:.\-@;,=%&]+)

username

string

exampleNew SIP

password

string

examplePassword

vbc

array

extension

string

example403

websocket

array

uri

string

examplewss://example.com/socket

Value must match regular expression ^(ws|wss)://[a-zA-Z0-9~#%@&-_?\/.,:;)(][]*$

content-type

string

exampleaudio/l16;rate=16000

Must be one of:audio/l16;rate=8000audio/l16;rate=16000

headers

object

Details of the Websocket to connect to

customer_id

string

exampleABC123

This is an example header. You can provide any headers you may need

sms

array

number

string

example447700900000

mms

array

number

string

example447700900000

array

number

string

example447700900000

viber

array

number

string

example447700900000

messenger

array

string

example12345abcd

_links

object

self

object

href

string

examplehttps://api.nexmo.com/v1/users/USR-82e028d9-5201-4f1e-8188-604b2d3471ec

Example Response

{
   "id": "USR-82e028d9-5201-4f1e-8188-604b2d3471ec",
   "name": "my_user_name",
   "display_name": "My User Name",
   "image_url": "https://example.com/image.png",
   "properties": {
      "custom_data": {
         "custom_key": "custom_value"
      },
      "ttl": 3600
   },
   "channels": {
      "pstn": [
         {
            "number": 123457
         }
      ],
      "sip": [
         {
            "uri": "sip:4442138907@sip.example.com;transport=tls",
            "username": "New SIP",
            "password": "Password"
         }
      ],
      "vbc": [
         {
            "extension": "403"
         }
      ],
      "websocket": [
         {
            "uri": "wss://example.com/socket",
            "content-type": "audio/l16;rate=16000",
            "headers": {
               "customer_id": "ABC123"
            }
         }
      ],
      "sms": [
         {
            "number": "447700900000"
         }
      ],
      "mms": [
         {
            "number": "447700900000"
         }
      ],
      "whatsapp": [
         {
            "number": "447700900000"
         }
      ],
      "viber": [
         {
            "number": "447700900000"
         }
      ],
      "messenger": [
         {
            "id": "12345abcd"
         }
      ]
   },
   "_links": {
      "self": {
         "href": "https://api.nexmo.com/v1/users/USR-82e028d9-5201-4f1e-8188-604b2d3471ec"
      }
   }
}

Retrieve a user

gethttps://api.nexmo.com/v1/users/:id

Authentication

Key	Description	Where	Example
Authorization	Your JSON web token. Read more about JWTs	Headers	`Bearer <JWT>`

Path Parameters

id | name

string

Required

exampleUSR-82e028d9-5201-4f1e-8188-604b2d3471ec

Unique ID or name for a user

Responses
Content Type
application/json

Retrieve a user

string

exampleUSR-82e028d9-5201-4f1e-8188-604b2d3471ec

User ID

name

string

examplemy_user_name

Unique name for a user

display_name

string

exampleMy User Name

A string to be displayed as user name. It does not need to be unique

image_url

string

examplehttps://example.com/image.png

An image URL that you associate with the user

properties

object

User properties

custom_data

object

example

{
  "custom_key": "custom_value"
}

custom key/value pairs

ttl

integer

Max2147483648

example3600

Time to live in seconds

channels

object

pstn

array

number

integer

example123457

sip

array

uri

string

examplesip:4442138907@sip.example.com;transport=tls

Value must match regular expression ^(sip|sips):\+?([\w|:.\-@;,=%&]+)

username

string

exampleNew SIP

password

string

examplePassword

vbc

array

extension

string

example403

websocket

array

uri

string

examplewss://example.com/socket

Value must match regular expression ^(ws|wss)://[a-zA-Z0-9~#%@&-_?\/.,:;)(][]*$

content-type

string

exampleaudio/l16;rate=16000

Must be one of:audio/l16;rate=8000audio/l16;rate=16000

headers

object

Details of the Websocket to connect to

customer_id

string

exampleABC123

This is an example header. You can provide any headers you may need

sms

array

number

string

example447700900000

mms

array

number

string

example447700900000

array

number

string

example447700900000

viber

array

number

string

example447700900000

messenger

array

string

example12345abcd

_links

object

self

object

href

string

examplehttps://api.nexmo.com/v1/users/USR-82e028d9-5201-4f1e-8188-604b2d3471ec

Example Response

{
   "id": "USR-82e028d9-5201-4f1e-8188-604b2d3471ec",
   "name": "my_user_name",
   "display_name": "My User Name",
   "image_url": "https://example.com/image.png",
   "properties": {
      "custom_data": {
         "custom_key": "custom_value"
      },
      "ttl": 3600
   },
   "channels": {
      "pstn": [
         {
            "number": 123457
         }
      ],
      "sip": [
         {
            "uri": "sip:4442138907@sip.example.com;transport=tls",
            "username": "New SIP",
            "password": "Password"
         }
      ],
      "vbc": [
         {
            "extension": "403"
         }
      ],
      "websocket": [
         {
            "uri": "wss://example.com/socket",
            "content-type": "audio/l16;rate=16000",
            "headers": {
               "customer_id": "ABC123"
            }
         }
      ],
      "sms": [
         {
            "number": "447700900000"
         }
      ],
      "mms": [
         {
            "number": "447700900000"
         }
      ],
      "whatsapp": [
         {
            "number": "447700900000"
         }
      ],
      "viber": [
         {
            "number": "447700900000"
         }
      ],
      "messenger": [
         {
            "id": "12345abcd"
         }
      ]
   },
   "_links": {
      "self": {
         "href": "https://api.nexmo.com/v1/users/USR-82e028d9-5201-4f1e-8188-604b2d3471ec"
      }
   }
}

Update a user

patchhttps://api.nexmo.com/v1/users/:id

Authentication

Key	Description	Where	Example
Authorization	Your JSON web token. Read more about JWTs	Headers	`Bearer <JWT>`

Path Parameters

string

Required

exampleUSR-82e028d9-5201-4f1e-8188-604b2d3471ec

Unique ID for a user

Request Body
Content Type
application/json

name

string

examplemy_user_name

Unique name for a user

display_name

string

exampleMy User Name

A string to be displayed as user name. It does not need to be unique

image_url

string

examplehttps://example.com/image.png

An image URL that you associate with the user

channels

object

pstn

array

number

integer

example123457

sip

array

uri

string

examplesip:4442138907@sip.example.com;transport=tls

Value must match regular expression ^(sip|sips):\+?([\w|:.\-@;,=%&]+)

username

string

exampleNew SIP

password

string

examplePassword

vbc

array

extension

string

example403

websocket

array

uri

string

examplewss://example.com/socket

Value must match regular expression ^(ws|wss)://[a-zA-Z0-9~#%@&-_?\/.,:;)(][]*$

content-type

string

exampleaudio/l16;rate=16000

Must be one of:audio/l16;rate=8000audio/l16;rate=16000

headers

object

Details of the Websocket to connect to

customer_id

string

exampleABC123

This is an example header. You can provide any headers you may need

sms

array

number

string

example447700900000

mms

array

number

string

example447700900000

array

number

string

example447700900000

viber

array

number

string

example447700900000

messenger

array

string

example12345abcd

Example Request

{
   "name": "my_user_name",
   "display_name": "My User Name",
   "image_url": "https://example.com/image.png",
   "channels": {
      "pstn": [
         {
            "number": 123457
         }
      ],
      "sip": [
         {
            "uri": "sip:4442138907@sip.example.com;transport=tls",
            "username": "New SIP",
            "password": "Password"
         }
      ],
      "vbc": [
         {
            "extension": "403"
         }
      ],
      "websocket": [
         {
            "uri": "wss://example.com/socket",
            "content-type": "audio/l16;rate=16000",
            "headers": {
               "customer_id": "ABC123"
            }
         }
      ],
      "sms": [
         {
            "number": "447700900000"
         }
      ],
      "mms": [
         {
            "number": "447700900000"
         }
      ],
      "whatsapp": [
         {
            "number": "447700900000"
         }
      ],
      "viber": [
         {
            "number": "447700900000"
         }
      ],
      "messenger": [
         {
            "id": "12345abcd"
         }
      ]
   }
}

{
   "name": "my_user_name",
   "display_name": "My User Name",
   "image_url": "https://example.com/image.png",
   "channels": {
      "pstn": [
         {
            "number": 123457
         }
      ],
      "sip": [
         {
            "uri": "sip:4442138907@sip.example.com;transport=tls",
            "username": "New SIP",
            "password": "Password"
         }
      ],
      "vbc": [
         {
            "extension": "403"
         }
      ],
      "websocket": [
         {
            "uri": "wss://example.com/socket",
            "content-type": "audio/l16;rate=16000",
            "headers": {
               "customer_id": "ABC123"
            }
         }
      ],
      "sms": [
         {
            "number": "447700900000"
         }
      ],
      "mms": [
         {
            "number": "447700900000"
         }
      ],
      "whatsapp": [
         {
            "number": "447700900000"
         }
      ],
      "viber": [
         {
            "number": "447700900000"
         }
      ],
      "messenger": [
         {
            "id": "12345abcd"
         }
      ]
   }
}

Responses
Content Type
application/json

Update a user

string

exampleUSR-82e028d9-5201-4f1e-8188-604b2d3471ec

User ID

name

string

examplemy_user_name

Unique name for a user

display_name

string

exampleMy User Name

A string to be displayed as user name. It does not need to be unique

image_url

string

examplehttps://example.com/image.png

An image URL that you associate with the user

properties

object

User properties

custom_data

object

example

{
  "custom_key": "custom_value"
}

custom key/value pairs

ttl

integer

Max2147483648

example3600

Time to live in seconds

channels

object

pstn

array

number

integer

example123457

sip

array

uri

string

examplesip:4442138907@sip.example.com;transport=tls

Value must match regular expression ^(sip|sips):\+?([\w|:.\-@;,=%&]+)

username

string

exampleNew SIP

password

string

examplePassword

vbc

array

extension

string

example403

websocket

array

uri

string

examplewss://example.com/socket

Value must match regular expression ^(ws|wss)://[a-zA-Z0-9~#%@&-_?\/.,:;)(][]*$

content-type

string

exampleaudio/l16;rate=16000

Must be one of:audio/l16;rate=8000audio/l16;rate=16000

headers

object

Details of the Websocket to connect to

customer_id

string

exampleABC123

This is an example header. You can provide any headers you may need

sms

array

number

string

example447700900000

mms

array

number

string

example447700900000

array

number

string

example447700900000

viber

array

number

string

example447700900000

messenger

array

string

example12345abcd

_links

object

self

object

href

string

examplehttps://api.nexmo.com/v1/users/USR-82e028d9-5201-4f1e-8188-604b2d3471ec

Example Response

{
   "id": "USR-82e028d9-5201-4f1e-8188-604b2d3471ec",
   "name": "my_user_name",
   "display_name": "My User Name",
   "image_url": "https://example.com/image.png",
   "properties": {
      "custom_data": {
         "custom_key": "custom_value"
      },
      "ttl": 3600
   },
   "channels": {
      "pstn": [
         {
            "number": 123457
         }
      ],
      "sip": [
         {
            "uri": "sip:4442138907@sip.example.com;transport=tls",
            "username": "New SIP",
            "password": "Password"
         }
      ],
      "vbc": [
         {
            "extension": "403"
         }
      ],
      "websocket": [
         {
            "uri": "wss://example.com/socket",
            "content-type": "audio/l16;rate=16000",
            "headers": {
               "customer_id": "ABC123"
            }
         }
      ],
      "sms": [
         {
            "number": "447700900000"
         }
      ],
      "mms": [
         {
            "number": "447700900000"
         }
      ],
      "whatsapp": [
         {
            "number": "447700900000"
         }
      ],
      "viber": [
         {
            "number": "447700900000"
         }
      ],
      "messenger": [
         {
            "id": "12345abcd"
         }
      ]
   },
   "_links": {
      "self": {
         "href": "https://api.nexmo.com/v1/users/USR-82e028d9-5201-4f1e-8188-604b2d3471ec"
      }
   }
}

Delete a user

Deleting a user cannot be undone.

deletehttps://api.nexmo.com/v1/users/:id

Authentication

Key	Description	Where	Example
Authorization	Your JSON web token. Read more about JWTs	Headers	`Bearer <JWT>`

Path Parameters

string

Required

exampleUSR-82e028d9-5201-4f1e-8188-604b2d3471ec

Unique ID for a user

Responses

Success response with no content

Errors

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 Information

Code	Information
payload-validation	Description Invalid request. See `invalid_parameters` field for details Resolution Review the documentation and send a valid `POST` request.
list-validation	Description Invalid request. See `invalid_parameters` field for details Resolution Review the documentation and send a valid `GET` request.
rate-limit	Description The request was rate limited Resolution The Redact API supports 170 requests per second. Reduce the frequency of your requests.

payload-validation

Description

Invalid request. See invalid_parameters field for details

Resolution

Review the documentation and send a valid POST request.

list-validation

Description

Invalid request. See invalid_parameters field for details

Resolution

Review the documentation and send a valid GET request.

rate-limit

Description

The request was rate limited

Resolution

The Redact API supports 170 requests per second. Reduce the frequency of your requests.

Application API

Application

Available Operations

List available applications

Authentication

Query Parameters

Responses Content Typeapplication/json

Example Response

Create an application

Authentication

Request Body Content Typeapplication/json

Example Request

Responses Content Typeapplication/json

Example Response

Get an application

Authentication

Path Parameters

Responses Content Typeapplication/json

Example Response

Update an application

Authentication

Path Parameters

Request Body Content Typeapplication/json

Example Request

Responses Content Typeapplication/json

Example Response

Delete an application

Authentication

Path Parameters

Responses

User

Available Operations

List users

Authentication

Query Parameters

Responses Content Typeapplication/json

Example Response

Create a user

Authentication

Request Body Content Typeapplication/json

Example Request

Responses Content Typeapplication/json

Example Response

Retrieve a user

Authentication

Path Parameters

Responses Content Typeapplication/json

Example Response

Update a user

Authentication

Path Parameters

Request Body Content Typeapplication/json

Example Request

Responses Content Typeapplication/json

Example Response

Delete a user

Authentication

Path Parameters

Responses

Errors

Responses
Content Type
application/json

Request Body
Content Type
application/json

Responses
Content Type
application/json

Responses
Content Type
application/json

Request Body
Content Type
application/json

Responses
Content Type
application/json

Responses
Content Type
application/json

Request Body
Content Type
application/json

Responses
Content Type
application/json

Responses
Content Type
application/json

Request Body
Content Type
application/json

Responses
Content Type
application/json