Available Operations
 
 

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
account_id
string
call_id
string
direction
string
One of: inbound or outbound
end_time
string
from
string
legs
array of objects
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 active
to
string

The "to" DID or extension

start_time
string
status
string
One of: busy, failed, unanswered, ringing or active
to
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
account_id
string
call_id
string
direction
string
One of: inbound or outbound
end_time
string
from
string
legs
array of objects
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 active
to
string

The "to" DID or extension

start_time
string
status
string
One of: busy, failed, unanswered, ringing or active
to
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
destination
string
type
string
Must be one of: device, extension or feature_code
to
object
destination
string
type
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
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 active
to
string

The "to" DID or extension

start_time
string
status
string
One of: busy, failed, unanswered, ringing or active
to
string
account_id
string
call_id
string
direction
string
One of: inbound or outbound
end_time
string
from
string
legs
array of objects
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 active
to
string

The "to" DID or extension

start_time
string
status
string
One of: busy, failed, unanswered, ringing or active
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
destination
string
type
string
Must be one of: device, extension or pstn
state
string
Must be one of: active or parked
to
object
destination
string
type
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 active
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 active
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 active
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 active
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

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://nexmo-community.github.io/ncco-examples/assets/voice_api_audio_streaming.mp3"
}

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 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
account_id
string
device_ip
string
is_registered
string
last_request
string
last_success
string
mac_address
string
registration
object
last_success
string
provisioned
object
last_success
string
last_request
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
account_id
string
device_ip
string
is_registered
string
last_request
string
last_success
string
mac_address
string
registration
object
last_success
string
provisioned
object
last_success
string
last_request
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",
      "is_registered": true,
      "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
is_registered
string
last_request
string
last_success
string
mac_address
string
registration
object
last_success
string
provisioned
object
last_success
string
last_request
string
account_id
string
device_ip
string
is_registered
string
last_request
string
last_success
string
mac_address
string
registration
object
last_success
string
provisioned
object
last_success
string
last_request
string

Example Responses

200 401 404
{
  "account_id": 1234,
  "device_ip": "150.24.83.17",
  "is_registered": true,
  "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