Telephony

The Vonage Business Telephony API enables you to manage calls and retrieve device registration information.

Download OpenAPI Specification

Available Operations

Get list of active calls for a given account (paginated). Please use Reports API to get list of completed calls.

gethttps://api.vonage.com/t/vbc.prod/telephony/v3/cc/accounts/:account_id/calls

Authentication

Key	Description	Where	Example
Authorization	Your OAuth token. Read more about OAuth tokens	Headers	`Bearer <access_token>`

Query Parameters

extension

string

example1234

page_size

string

Default100

example100

Return max this amount of calls in the response.

order

string

exampleasc

Either ascending or descending order.
Must be one of asc or desc.

start_time

string

example1595955770

Return the calls that occurred after this point in time.
Should be of type epoch with seconds precision.

end_time

integer

example1595955770

Return the calls that occurred before this point in time.
Should be of type epoch with seconds precision.

Path Parameters

account_id

string

Required

example1234

Responses
Content Type
application/json

200 response

calls

array

account_id

string

example1234

call_id

string

example3fa85f64-5717-4562-b3fc-2c963f66afa6

direction

string

exampleinbound

Must be one of:inboundoutbound

end_time

string(date-time)

example1595959736

from

string

example1235551111

legs

array

account_id

string

example1234

Account that this call leg belongs to

call_id

string(uuid)

example3fa85f64-5717-4562-b3fc-2c963f66afa6

Call Id this call belongs to

direction

string

exampleinbound

Leg direction - either "inbound" or "outbound"

Must be one of:inboundoutbound

end_time

string(date-time)

example1595959736

Call end time (if applicable)

from

string

example1231112222

The "from" DID or extension

leg_id

string(uuid)

example3fa85f64-5717-4562-b3fc-2c963f66afa6

Globally unique leg Id

start_time

string(date-time)

example1595959736

Call start time

status

string

examplebusy

current leg status

Must be one of:busyfailedunansweredringingon-call

string

example1234567890

The "to" DID or extension

start_time

string(date-time)

example1595959736

status

string

examplebusy

Must be one of:busyfailedunansweredringingon-call

string

example1234567890

current_page

string

first_page_uri

string

example/cc/accounts/1234/calls?page_size=0&order=desc

next_page

string

example1

next_page_uri

string

example/cc/accounts/1234/calls?page_size=0&order=desc

order

string

exampledesc

page_size

string

example1

pages

string

example1

previous_page_uri

string

example/cc/accounts/1234/calls?page_size=0&order=desc

Example Response

{
   "calls": [
      {
         "account_id": 1234,
         "call_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
         "direction": "inbound",
         "end_time": 1595959736,
         "from": 1235551111,
         "legs": [
            {
               "account_id": 1234,
               "call_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
               "direction": "inbound",
               "end_time": 1595959736,
               "from": 1231112222,
               "leg_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
               "start_time": 1595959736,
               "status": "busy",
               "to": 1234567890
            }
         ],
         "start_time": 1595959736,
         "status": "busy",
         "to": 1234567890
      }
   ],
   "current_page": 0,
   "first_page_uri": "/cc/accounts/1234/calls?page_size=0&order=desc",
   "next_page": 1,
   "next_page_uri": "/cc/accounts/1234/calls?page_size=0&order=desc",
   "order": "desc",
   "page_size": 1,
   "pages": 1,
   "previous_page_uri": "/cc/accounts/1234/calls?page_size=0&order=desc"
}

Create a new call

posthttps://api.vonage.com/t/vbc.prod/telephony/v3/cc/accounts/:account_id/calls

Authentication

Key	Description	Where	Example
Authorization	Your OAuth token. Read more about OAuth tokens	Headers	`Bearer <access_token>`

Path Parameters

account_id

string

Required

example1234

Request Body
Content Type
application/json

from

object

destination

string

example1234

type

string

exampleextension

Must be one of:deviceextensionfeature_code

object

destination

string

example1234567890

type

string

examplepstn

Must be one of:deviceextensionpstnfeature_code

type

string

exampleclick2dial

Must be one of:click2dialclick2dialmeodrdefault

Example Request

{
   "from": {
      "destination": 1234,
      "type": "extension"
   },
   "to": {
      "destination": 1234567890,
      "type": "pstn"
   },
   "type": "click2dial"
}

{
   "from": {
      "destination": 1234,
      "type": "extension"
   },
   "to": {
      "destination": 1234567890,
      "type": "pstn"
   },
   "type": "click2dial"
}

Responses
Content Type
text/plain

200 response

Example Response

Example preview is currently not supported for content type: text/plain

Get details for a specific active call.

gethttps://api.vonage.com/t/vbc.prod/telephony/v3/cc/accounts/:account_id/calls/:call_id

Authentication

Key	Description	Where	Example
Authorization	Your OAuth token. Read more about OAuth tokens	Headers	`Bearer <access_token>`

Path Parameters

account_id

string

Required

example1234

call_id

string

Required

example3fa85f64-5717-4562-b3fc-2c963f66afa6

Responses
Content Type
application/json

200 response

account_id

string

example1234

call_id

string

example3fa85f64-5717-4562-b3fc-2c963f66afa6

direction

string

exampleinbound

Must be one of:inboundoutbound

end_time

string(date-time)

example1595959736

from

string

example1235551111

legs

array

account_id

string

example1234

Account that this call leg belongs to

call_id

string(uuid)

example3fa85f64-5717-4562-b3fc-2c963f66afa6

Call Id this call belongs to

direction

string

exampleinbound

Leg direction - either "inbound" or "outbound"

Must be one of:inboundoutbound

end_time

string(date-time)

example1595959736

Call end time (if applicable)

from

string

example1231112222

The "from" DID or extension

leg_id

string(uuid)

example3fa85f64-5717-4562-b3fc-2c963f66afa6

Globally unique leg Id

start_time

string(date-time)

example1595959736

Call start time

status

string

examplebusy

current leg status

Must be one of:busyfailedunansweredringingon-call

string

example1234567890

The "to" DID or extension

start_time

string(date-time)

example1595959736

status

string

examplebusy

Must be one of:busyfailedunansweredringingon-call

string

example1234567890

Example Response

{
   "account_id": 1234,
   "call_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
   "direction": "inbound",
   "end_time": 1595959736,
   "from": 1235551111,
   "legs": [
      {
         "account_id": 1234,
         "call_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
         "direction": "inbound",
         "end_time": 1595959736,
         "from": 1231112222,
         "leg_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
         "start_time": 1595959736,
         "status": "busy",
         "to": 1234567890
      }
   ],
   "start_time": 1595959736,
   "status": "busy",
   "to": 1234567890
}

Update an existing call

puthttps://api.vonage.com/t/vbc.prod/telephony/v3/cc/accounts/:account_id/calls/:call_id

Authentication

Key	Description	Where	Example
Authorization	Your OAuth token. Read more about OAuth tokens	Headers	`Bearer <access_token>`

Path Parameters

account_id

string

Required

example12345

call_id

string

Required

examplec91150a6-8cc4-4e73-9fef-17fd925c6448

Request Body
Content Type
application/json

from

object

destination

string

example1234567890

type

string

examplepstn

Must be one of:deviceextensionpstn

state

string

Must be one of:activeparked

object

destination

string

example1234567890

type

string

examplepstn

Must be one of:deviceextensionpstn

Example Request

{
   "from": {
      "destination": 1234567890,
      "type": "pstn"
   },
   "state": "active",
   "to": {
      "destination": 1234567890,
      "type": "pstn"
   }
}

{
   "from": {
      "destination": 1234567890,
      "type": "pstn"
   },
   "state": "active",
   "to": {
      "destination": 1234567890,
      "type": "pstn"
   }
}

Responses
Content Type
application/json

200 response

account_id

string(integer)

example1234

call_id

string(uuid)

example3fa85f64-5717-4562-b3fc-2c963f66afa6

call_state

string

destination

string

Example Response

{
   "account_id": 1234,
   "call_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
   "call_state": "string",
   "destination": "string"
}

Delete a call resource

deletehttps://api.vonage.com/t/vbc.prod/telephony/v3/cc/accounts/:account_id/calls/:call_id

Authentication

Key	Description	Where	Example
Authorization	Your OAuth token. Read more about OAuth tokens	Headers	`Bearer <access_token>`

Path Parameters

account_id

string

Required

example1234

call_id

string

Required

example3fa85f64-5717-4562-b3fc-2c963f66afa6

Responses
Content Type
application/json

200 response

account_id

string(integer)

example1234

call_id

string(uuid)

example3fa85f64-5717-4562-b3fc-2c963f66afa6

call_state

string

destination

string

Example Response

{
   "account_id": 1234,
   "call_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
   "call_state": "string",
   "destination": "string"
}

Get list of legs for a given active call

gethttps://api.vonage.com/t/vbc.prod/telephony/v3/cc/accounts/:account_id/calls/:call_id/legs

Authentication

Key	Description	Where	Example
Authorization	Your OAuth token. Read more about OAuth tokens	Headers	`Bearer <access_token>`

Path Parameters

account_id

string

Required

example1234

call_id

string

Required

example3fa85f64-5717-4562-b3fc-2c963f66afa6

Responses
Content Type
application/json

200 response

array

account_id

string

example1234

Account that this call leg belongs to

call_id

string(uuid)

example3fa85f64-5717-4562-b3fc-2c963f66afa6

Call Id this call belongs to

direction

string

exampleinbound

Leg direction - either "inbound" or "outbound"

Must be one of:inboundoutbound

end_time

string(date-time)

example1595959736

Call end time (if applicable)

from

string

example1231112222

The "from" DID or extension

leg_id

string(uuid)

example3fa85f64-5717-4562-b3fc-2c963f66afa6

Globally unique leg Id

start_time

string(date-time)

example1595959736

Call start time

status

string

examplebusy

current leg status

Must be one of:busyfailedunansweredringingon-call

string

example1234567890

The "to" DID or extension

Example Response

[
   {
      "account_id": 1234,
      "call_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "direction": "inbound",
      "end_time": 1595959736,
      "from": 1231112222,
      "leg_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "start_time": 1595959736,
      "status": "busy",
      "to": 1234567890
   }
]

Get details for a specific active call leg

gethttps://api.vonage.com/t/vbc.prod/telephony/v3/cc/accounts/:account_id/calls/:call_id/legs/:leg_id

Authentication

Key	Description	Where	Example
Authorization	Your OAuth token. Read more about OAuth tokens	Headers	`Bearer <access_token>`

Path Parameters

leg_id

string

Required

example3fa85f64-5717-4562-b3fc-2c963f66afa6

account_id

string

Required

example1234

call_id

string

Required

example3fa85f64-5717-4562-b3fc-2c963f66afa6

Responses
Content Type
application/json

200 response

account_id

string

example1234

Account that this call leg belongs to

call_id

string(uuid)

example3fa85f64-5717-4562-b3fc-2c963f66afa6

Call Id this call belongs to

direction

string

exampleinbound

Leg direction - either "inbound" or "outbound"

Must be one of:inboundoutbound

end_time

string(date-time)

example1595959736

Call end time (if applicable)

from

string

example1231112222

The "from" DID or extension

leg_id

string(uuid)

example3fa85f64-5717-4562-b3fc-2c963f66afa6

Globally unique leg Id

start_time

string(date-time)

example1595959736

Call start time

status

string

examplebusy

current leg status

Must be one of:busyfailedunansweredringingon-call

string

example1234567890

The "to" DID or extension

Example Response

{
   "account_id": 1234,
   "call_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
   "direction": "inbound",
   "end_time": 1595959736,
   "from": 1231112222,
   "leg_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
   "start_time": 1595959736,
   "status": "busy",
   "to": 1234567890
}

Modify a call leg.

puthttps://api.vonage.com/t/vbc.prod/telephony/v3/cc/accounts/:account_id/calls/:call_id/legs/:leg_id

Authentication

Key	Description	Where	Example
Authorization	Your OAuth token. Read more about OAuth tokens	Headers	`Bearer <access_token>`

Path Parameters

account_id

string

Required

example1234

call_id

string

Required

example3fa85f64-5717-4562-b3fc-2c963f66afa6

leg_id

string

Required

example3fa85f64-5717-4562-b3fc-2c963f66afa6

Request Body
Content Type
application/json

One Of

state

string

exampleheld

Example Request

{
   "state": "held"
}

{
   "state": "held"
}

Responses
Content Type
application/json

200 response

account_id

string(integer)

example1234

call_id

string(uuid)

call_state

string

destination

string

leg_id

string(uuid)

example3fa85f64-5717-4562-b3fc-2c963f66afa6

Example Response

{
   "account_id": 1234,
   "call_id": "0d0a16ab-a508-4d58-bf24-5dc3cb248f3e",
   "call_state": "string",
   "destination": "string",
   "leg_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}

Delete a call leg.

deletehttps://api.vonage.com/t/vbc.prod/telephony/v3/cc/accounts/:account_id/calls/:call_id/legs/:leg_id

Authentication

Key	Description	Where	Example
Authorization	Your OAuth token. Read more about OAuth tokens	Headers	`Bearer <access_token>`

Path Parameters

account_id

string

Required

example1234

call_id

string

Required

example3fa85f64-5717-4562-b3fc-2c963f66afa6

leg_id

string

Required

example3fa85f64-5717-4562-b3fc-2c963f66afa6

Responses
Content Type

204 response

Get account device's registration info

gethttps://api.vonage.com/t/vbc.prod/telephony/v3/registration/accounts/:account_id/devices

Authentication

Key	Description	Where	Example
Authorization	Your OAuth token. Read more about OAuth tokens	Headers	`Bearer <access_token>`

Query Parameters

page_size

string

Default100

example10

Return max this number of devices in the response.

order

string

exampleasc

Either ascending or descending order.
Must be one of asc or desc.

start_time

string

example1595955770

Return the devices that were registered after this point in time.
Should be of type epoch with seconds precision.

end_time

integer

example1595955770

Return the devices that were registered before this point in time.
Should be of type epoch with seconds precision.

Path Parameters

account_id

string

Required

example1234

Responses
Content Type
application/json

200 response

current_page

string

example1

devices

array

account_id

string

example1234

device_ip

string

example150.24.83.17

last_request

string

example1595937421

last_success

string

example1595937421

mac_address

string

example79-5C-7D-28-1B-B3

registration

object

last_success

string

example1595937421

provisioned

object

last_success

string

example1595937421

last_request

string

example1595937421

first_page_uri

string

example/registration/accounts/1234/devices?page_size=100&order=desc

next_page

string

next_page_uri

string

example/registration/accounts/1234/devices?page_size=100&order=desc

order

string

exampledesc

page_size

string

example10

pages

string

example2

previous_page_uri

string

example/registration/accounts/1234/devices?page_size=100&order=desc

Example Response

{
   "current_page": 1,
   "devices": [
      {
         "account_id": 1234,
         "device_ip": "150.24.83.17",
         "last_request": 1595937421,
         "last_success": 1595937421,
         "mac_address": "79-5C-7D-28-1B-B3",
         "registration": {
            "last_success": 1595937421
         },
         "provisioned": {
            "last_success": 1595937421,
            "last_request": 1595937421
         }
      }
   ],
   "first_page_uri": "/registration/accounts/1234/devices?page_size=100&order=desc",
   "next_page": "string",
   "next_page_uri": "/registration/accounts/1234/devices?page_size=100&order=desc",
   "order": "desc",
   "page_size": 10,
   "pages": 2,
   "previous_page_uri": "/registration/accounts/1234/devices?page_size=100&order=desc"
}

Get device registration info

gethttps://api.vonage.com/t/vbc.prod/telephony/v3/registration/accounts/:account_id/devices/:device_id

Authentication

Key	Description	Where	Example
Authorization	Your OAuth token. Read more about OAuth tokens	Headers	`Bearer <access_token>`

Path Parameters

account_id

string

Required

example1234

device_id

string

Required

example38-99-62-93-E2-A9

Mac address of device

Responses
Content Type
application/json

200 response

account_id

string

example1234

device_ip

string

example150.24.83.17

last_request

string

example1595937421

last_success

string

example1595937421

mac_address

string

example79-5C-7D-28-1B-B3

registration

object

last_success

string

example1595937421

provisioned

object

last_success

string

example1595937421

last_request

string

example1595937421

Example Response

{
   "account_id": 1234,
   "device_ip": "150.24.83.17",
   "last_request": 1595937421,
   "last_success": 1595937421,
   "mac_address": "79-5C-7D-28-1B-B3",
   "registration": {
      "last_success": 1595937421
   },
   "provisioned": {
      "last_success": 1595937421,
      "last_request": 1595937421
   }
}

Telephony

Available Operations

Get list of active calls for a given account (paginated). Please use Reports API to get list of completed calls.

Authentication

Query Parameters

Path Parameters

Responses Content Typeapplication/json

Example Response

Create a new call

Authentication

Path Parameters

Request Body Content Typeapplication/json

Example Request

Responses Content Typetext/plain

Example Response

Get details for a specific active call.

Authentication

Path Parameters

Responses Content Typeapplication/json

Example Response

Update an existing call

Authentication

Path Parameters

Request Body Content Typeapplication/json

Example Request

Responses Content Typeapplication/json

Example Response

Delete a call resource

Authentication

Path Parameters

Responses Content Typeapplication/json

Example Response

Get list of legs for a given active call

Authentication

Path Parameters

Responses Content Typeapplication/json

Example Response

Get details for a specific active call leg

Authentication

Path Parameters

Responses Content Typeapplication/json

Example Response

Modify a call leg.

Authentication

Path Parameters

Request Body Content Typeapplication/json

Example Request

Responses Content Typeapplication/json

Example Response

Delete a call leg.

Authentication

Path Parameters

Responses Content Type

Get account device's registration info

Authentication

Query Parameters

Path Parameters

Responses Content Typeapplication/json

Example Response

Get device registration info

Authentication

Path Parameters

Responses Content Typeapplication/json

Example Response

Responses
Content Type
application/json

Request Body
Content Type
application/json

Responses
Content Type
text/plain

Responses
Content Type
application/json

Request Body
Content Type
application/json

Responses
Content Type
application/json

Responses
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

Responses
Content Type
application/json

Responses
Content Type
application/json