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

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

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

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

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

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

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

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

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

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

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

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

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