Telephony

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

Available Operations:

get Get list of active calls for a given account (paginated). Please use Reports API to get list of completed calls.
post Create a new call
get Get details for a specific active call.
put Update an existing call
delete Delete a call resource
get Get list of legs for a given active call
get Get details for a specific active call leg
put Modify a call leg.
delete Delete a call leg.
get Get account device's registration info
get Get device registration info

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

GET


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

Host


        https://api.vonage.com

GET


        /t/vbc.prod/telephony/v3/cc/accounts/:account_id/calls

Authentication

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

Path Parameters

account_id

string | Required

Query Parameter

extension

string

page_size

string | Default: 100

Return max this amount of calls in the response.

order

string

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

start_time

string

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

end_time

integer

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

Responses

200 200 response

calls

array of objects

string

One of: inbound or outbound

string

array of objects

string

Account that this call leg belongs to

string

Call Id this call belongs to

string

Leg direction - either "inbound" or "outbound"

One of: inbound or outbound

string

Call end time (if applicable)

string

The "from" DID or extension

string

Globally unique leg Id

string

Call start time

string

current leg status

One of: busy, failed, unanswered, ringing or on-call

string

The "to" DID or extension

string

One of: busy, failed, unanswered, ringing or on-call

string

current_page

string

first_page_uri

string

next_page

string

next_page_uri

string

order

string

page_size

string

pages

string

previous_page_uri

string

calls

array of objects

string

One of: inbound or outbound

string

array of objects

string

Account that this call leg belongs to

string

Call Id this call belongs to

string

Leg direction - either "inbound" or "outbound"

One of: inbound or outbound

string

Call end time (if applicable)

string

The "from" DID or extension

string

Globally unique leg Id

string

Call start time

string

current leg status

One of: busy, failed, unanswered, ringing or on-call

string

The "to" DID or extension

string

One of: busy, failed, unanswered, ringing or on-call

string

current_page

string

first_page_uri

string

next_page

string

next_page_uri

string

order

string

page_size

string

pages

string

previous_page_uri

string

Example Responses

200 401 404

{
  "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"
}

200 response

{
  "code": 401,
  "message": "User is not permitted to make a request against this account"
}

401 response

{
  "code": 401,
  "message": "No matching resource found for given API Request"
}

404 response

Create a new call

POST


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

Host


        https://api.vonage.com

POST


        /t/vbc.prod/telephony/v3/cc/accounts/:account_id/calls

Authentication

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

Path Parameters

account_id

string | Required

Request body application/json

Request body description

from

object

string

Must be one of: device, extension or feature_code

to

object

string

Must be one of: device, extension, pstn or feature_code

type

string

Must be one of: click2dial, click2dialme, odr or default

Responses

200 200 response

Example Request

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

Example Responses

200 400 401

200 response

"e2610a31-88be-4f12-90c0-ee98dbfaf80b"

400 response

{
  "code": 400,
  "message": "Invalid request parameters"
}

401 response

{
  "code": 401,
  "message": "User is not permitted to make a request against this account"
}

Get details for a specific active call.

GET


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

Host


        https://api.vonage.com

GET


        /t/vbc.prod/telephony/v3/cc/accounts/:account_id/calls/:call_id

Authentication

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

Path Parameters

account_id

string | Required

call_id

string | Required

Responses

200 200 response

account_id

string

call_id

string

direction

string

One of: inbound or outbound

end_time

string

from

string

legs

array of objects

string

Account that this call leg belongs to

string

Call Id this call belongs to

string

Leg direction - either "inbound" or "outbound"

One of: inbound or outbound

string

Call end time (if applicable)

string

The "from" DID or extension

string

Globally unique leg Id

string

Call start time

string

current leg status

One of: busy, failed, unanswered, ringing or on-call

string

The "to" DID or extension

start_time

string

status

string

One of: busy, failed, unanswered, ringing or on-call

to

string

account_id

string

call_id

string

direction

string

One of: inbound or outbound

end_time

string

from

string

legs

array of objects

string

Account that this call leg belongs to

string

Call Id this call belongs to

string

Leg direction - either "inbound" or "outbound"

One of: inbound or outbound

string

Call end time (if applicable)

string

The "from" DID or extension

string

Globally unique leg Id

string

Call start time

string

current leg status

One of: busy, failed, unanswered, ringing or on-call

string

The "to" DID or extension

start_time

string

status

string

One of: busy, failed, unanswered, ringing or on-call

to

string

Example Responses

200 401 404

{
  "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
}

200 response

{
  "code": 401,
  "message": "User is not permitted to make a request against this account"
}

401 response

{
  "code": 401,
  "message": "No matching resource found for given API Request"
}

404 response

Update an existing call

PUT


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

Host


        https://api.vonage.com

PUT


        /t/vbc.prod/telephony/v3/cc/accounts/:account_id/calls/:call_id

Authentication

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

Path Parameters

account_id

string | Required

call_id

string | Required

Request body application/json

To answer a call: 'state' should be 'active', and 'to' should include the VH id of the device answering the call. To transfer a call: 'state' should not be specified. Both 'to' and 'from' should be specified. To park a call: 'state' should be 'parked', and 'from' should be specified.

from

object

string

Must be one of: device, extension or pstn

state

string

Must be one of: active or parked

to

object

string

Must be one of: device, extension or pstn

Responses

200 200 response

account_id

string

call_id

string

call_state

string

destination

string

Example Request

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

Example Responses

200 400 401 404

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

{
  "code": 400,
  "message": "Invalid request parameters"
}

{
  "code": 401,
  "message": "User is not permitted to make a request against this account"
}

{
  "code": 401,
  "message": "No matching resource found for given API Request"
}

Delete a call resource

DELETE


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

Host


        https://api.vonage.com

DELETE


        /t/vbc.prod/telephony/v3/cc/accounts/:account_id/calls/:call_id

Authentication

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

Path Parameters

account_id

string | Required

call_id

string | Required

Responses

200 200 response

account_id

string

call_id

string

call_state

string

destination

string

account_id

string

call_id

string

call_state

string

destination

string

Example Responses

200 401 404

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

200 response

{
  "code": 401,
  "message": "User is not permitted to make a request against this account"
}

401 response

{
  "code": 401,
  "message": "No matching resource found for given API Request"
}

404 response

Get list of legs for a given active call

GET


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

Host


        https://api.vonage.com

GET


        /t/vbc.prod/telephony/v3/cc/accounts/:account_id/calls/:call_id/legs

Authentication

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

Path Parameters

account_id

string | Required

call_id

string | Required

Responses

200 200 response

account_id

string

Account that this call leg belongs to

call_id

string

Call Id this call belongs to

direction

string

Leg direction - either "inbound" or "outbound"

One of: inbound or outbound

end_time

string

Call end time (if applicable)

from

string

The "from" DID or extension

leg_id

string

Globally unique leg Id

start_time

string

Call start time

status

string

current leg status

One of: busy, failed, unanswered, ringing or on-call

to

string

The "to" DID or extension

account_id

string

Account that this call leg belongs to

call_id

string

Call Id this call belongs to

direction

string

Leg direction - either "inbound" or "outbound"

One of: inbound or outbound

end_time

string

Call end time (if applicable)

from

string

The "from" DID or extension

leg_id

string

Globally unique leg Id

start_time

string

Call start time

status

string

current leg status

One of: busy, failed, unanswered, ringing or on-call

to

string

The "to" DID or extension

Example Responses

200 401

[
  {
    "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
  }
]

200 response

{
  "code": 401,
  "message": "User is not permitted to make a request against this account"
}

401 response

Get details for a specific active call leg

GET


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

Host


        https://api.vonage.com

GET


        /t/vbc.prod/telephony/v3/cc/accounts/:account_id/calls/:call_id/legs/:leg_id

Authentication

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

Path Parameters

leg_id

string | Required

account_id

string | Required

call_id

string | Required

Responses

200 200 response

account_id

string

Account that this call leg belongs to

call_id

string

Call Id this call belongs to

direction

string

Leg direction - either "inbound" or "outbound"

One of: inbound or outbound

end_time

string

Call end time (if applicable)

from

string

The "from" DID or extension

leg_id

string

Globally unique leg Id

start_time

string

Call start time

status

string

current leg status

One of: busy, failed, unanswered, ringing or on-call

to

string

The "to" DID or extension

account_id

string

Account that this call leg belongs to

call_id

string

Call Id this call belongs to

direction

string

Leg direction - either "inbound" or "outbound"

One of: inbound or outbound

end_time

string

Call end time (if applicable)

from

string

The "from" DID or extension

leg_id

string

Globally unique leg Id

start_time

string

Call start time

status

string

current leg status

One of: busy, failed, unanswered, ringing or on-call

to

string

The "to" DID or extension

Example Responses

200 401

{
  "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
}

200 response

{
  "code": 401,
  "message": "User is not permitted to make a request against this account"
}

401 response

Modify a call leg.

PUT


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

Host


        https://api.vonage.com

PUT


        /t/vbc.prod/telephony/v3/cc/accounts/:account_id/calls/:call_id/legs/:leg_id

Authentication

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

Path Parameters

account_id

string | Required

call_id

string | Required

leg_id

string | Required

Request body application/json

Perform hold or unhold or send dtmf or transfer on the call leg.

state

string

state

string

dtmf

string

stream

boolean

stream_url

string

stream

boolean

state

string

to

object

state

string

to

object

state

string

recording

string

service

string

recording

string

service

string

recording

string

service

string

recording

string

service

string

Responses

200 200 response

account_id

string

call_id

string

call_state

string

destination

string

leg_id

string

Example Request » Hold » Held

{
  "state": "held"
}

Example Request » Hold » Unhold

{
  "state": "active"
}

Example Request » DTMF

{
  "dtmf": "*123#"
}

Example Request » Play Sound

{
  "stream": true,
  "stream_url": "https://example.com/recorded_message.wav"
}

Example Request » Stop Sound

{
}

Example Request » Blind XFER

{
  "state": "active",
  "to": "{'destination': Contact, 'type': ttype}"
}

Example Request » ATT XFER

{
  "state": "active",
  "to": "{'destination': leg_id,'type': 'leg'}"
}

Example Request » Active

{
  "state": "active"
}

Example Request » Record » CCR Start

{
  "recording": "start",
  "service": "ccr"
}

Example Request » Record » CCR Stop

{
  "recording": "stop",
  "service": "ccr"
}

Example Request » Record » OCR Start

{
  "recording": "start",
  "service": "ocr"
}

Example Request » Record » OCR Stop

{
  "recording": "stop",
  "service": "ocr"
}

Example Responses

200 400 401 404 409

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

{
  "code": 400,
  "message": "Invalid request parameters"
}

{
  "code": 401,
  "message": "User is not permitted to make a request against this account"
}

{
  "code": 401,
  "message": "No matching resource found for given API Request"
}

{
  "code": 400,
  "message": "Invalid request parameters"
}

Delete a call leg.

DELETE


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

Host


        https://api.vonage.com

DELETE


        /t/vbc.prod/telephony/v3/cc/accounts/:account_id/calls/:call_id/legs/:leg_id

Authentication

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

Path Parameters

account_id

string | Required

call_id

string | Required

leg_id

string | Required

Responses

204 204 response

This endpoint does not support application/json

Example Responses

204 400 401 404 409

204 response

{
  "code": 400,
  "message": "Invalid request parameters"
}

{
  "code": 401,
  "message": "User is not permitted to make a request against this account"
}

{
  "code": 401,
  "message": "No matching resource found for given API Request"
}

{
  "code": 400,
  "message": "Invalid request parameters"
}

Get account device's registration info

GET


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

Host


        https://api.vonage.com

GET


        /t/vbc.prod/telephony/v3/registration/accounts/:account_id/devices

Authentication

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

Path Parameters

account_id

string | Required

Query Parameter

page_size

string | Default: 100

Return max this number of devices in the response.

order

string

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

start_time

string

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

end_time

integer

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

Responses

200 200 response

current_page

string

devices

array of objects

string

object

string

object

string

first_page_uri

string

next_page

string

next_page_uri

string

order

string

page_size

string

pages

string

previous_page_uri

string

current_page

string

devices

array of objects

string

object

string

object

string

first_page_uri

string

next_page

string

next_page_uri

string

order

string

page_size

string

pages

string

previous_page_uri

string

Example Responses

200 401

{
  "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": "abc123",
  "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"
}

200 response

{
  "code": 401,
  "message": "User is not permitted to make a request against this account"
}

401 response

Get device registration info

GET


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

Host


        https://api.vonage.com

GET


        /t/vbc.prod/telephony/v3/registration/accounts/:account_id/devices/:device_id

Authentication

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

Path Parameters

account_id

string | Required

device_id

string | Required

Mac address of device

Responses

200 200 response

account_id

string

device_ip

string

last_request

string

last_success

string

mac_address

string

registration

object

string

provisioned

object

string

account_id

string

device_ip

string

last_request

string

last_success

string

mac_address

string

registration

object

string

provisioned

object

string

Example Responses

200 401 404

{
  "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
  }
}

200 response

{
  "code": 401,
  "message": "User is not permitted to make a request against this account"
}

401 response

{
  "code": 401,
  "message": "No matching resource found for given API Request"
}

404 response