The Vonage Business Telephony API enables you to manage calls and retrieve device registration information.
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
| Key | Description | Example | Default |
|---|---|---|---|
| Authorization |
Your OAuth token. Read more about OAuth tokens |
Bearer <access_token> |
None |
Return max this amount of calls in the response.
Either ascending or descending order.
Must be one of asc or desc.
Return the calls that occurred after this point in time.
Should be of type epoch with seconds precision.
Return the calls that occurred before this point in time.
Should be of type epoch with seconds precision.
inbound or outbound
Account that this call leg belongs to
Call Id this call belongs to
Leg direction - either "inbound" or "outbound"
One of:inbound or outbound
Call end time (if applicable)
The "from" DID or extension
Globally unique leg Id
Call start time
current leg status
One of:busy, failed, unanswered, ringing or on-call
The "to" DID or extension
busy, failed, unanswered, ringing or on-call
inbound or outbound
Account that this call leg belongs to
Call Id this call belongs to
Leg direction - either "inbound" or "outbound"
One of:inbound or outbound
Call end time (if applicable)
The "from" DID or extension
Globally unique leg Id
Call start time
current leg status
One of:busy, failed, unanswered, ringing or on-call
The "to" DID or extension
busy, failed, unanswered, ringing or on-call
{
"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 responsePOST
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
| Key | Description | Example | Default |
|---|---|---|---|
| Authorization |
Your OAuth token. Read more about OAuth tokens |
Bearer <access_token> |
None |
Request body description
device, extension or feature_code
device, extension, pstn or feature_code
click2dial, click2dialme, odr or default
{
"from": {
"destination": 1234,
"type": "extension"
},
"to": {
"destination": 1234567890,
"type": "pstn"
},
"type": "click2dial"
}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
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
| Key | Description | Example | Default |
|---|---|---|---|
| Authorization |
Your OAuth token. Read more about OAuth tokens |
Bearer <access_token> |
None |
inbound or outbound
Account that this call leg belongs to
Call Id this call belongs to
Leg direction - either "inbound" or "outbound"
One of:inbound or outbound
Call end time (if applicable)
The "from" DID or extension
Globally unique leg Id
Call start time
current leg status
One of:busy, failed, unanswered, ringing or on-call
The "to" DID or extension
busy, failed, unanswered, ringing or on-call
inbound or outbound
Account that this call leg belongs to
Call Id this call belongs to
Leg direction - either "inbound" or "outbound"
One of:inbound or outbound
Call end time (if applicable)
The "from" DID or extension
Globally unique leg Id
Call start time
current leg status
One of:busy, failed, unanswered, ringing or on-call
The "to" DID or extension
busy, failed, unanswered, ringing or on-call
{
"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 responsePUT
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
| Key | Description | Example | Default |
|---|---|---|---|
| Authorization |
Your OAuth token. Read more about OAuth tokens |
Bearer <access_token> |
None |
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.
device, extension or pstn
active or parked
device, extension or pstn
{
"from": {
"destination": 1234567890,
"type": "pstn"
},
"to": {
"destination": 1234567890,
"type": "pstn"
}
}{
"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
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
| Key | Description | Example | Default |
|---|---|---|---|
| Authorization |
Your OAuth token. Read more about OAuth tokens |
Bearer <access_token> |
None |
{
"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 responseGET
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
| Key | Description | Example | Default |
|---|---|---|---|
| Authorization |
Your OAuth token. Read more about OAuth tokens |
Bearer <access_token> |
None |
Account that this call leg belongs to
Call Id this call belongs to
Leg direction - either "inbound" or "outbound"
One of:inbound or outbound
Call end time (if applicable)
The "from" DID or extension
Globally unique leg Id
Call start time
current leg status
One of:busy, failed, unanswered, ringing or on-call
The "to" DID or extension
Account that this call leg belongs to
Call Id this call belongs to
Leg direction - either "inbound" or "outbound"
One of:inbound or outbound
Call end time (if applicable)
The "from" DID or extension
Globally unique leg Id
Call start time
current leg status
One of:busy, failed, unanswered, ringing or on-call
The "to" DID or extension
[
{
"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 responseGET
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
| Key | Description | Example | Default |
|---|---|---|---|
| Authorization |
Your OAuth token. Read more about OAuth tokens |
Bearer <access_token> |
None |
Account that this call leg belongs to
Call Id this call belongs to
Leg direction - either "inbound" or "outbound"
One of:inbound or outbound
Call end time (if applicable)
The "from" DID or extension
Globally unique leg Id
Call start time
current leg status
One of:busy, failed, unanswered, ringing or on-call
The "to" DID or extension
Account that this call leg belongs to
Call Id this call belongs to
Leg direction - either "inbound" or "outbound"
One of:inbound or outbound
Call end time (if applicable)
The "from" DID or extension
Globally unique leg Id
Call start time
current leg status
One of:busy, failed, unanswered, ringing or on-call
The "to" DID or extension
{
"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 responsePUT
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
| Key | Description | Example | Default |
|---|---|---|---|
| Authorization |
Your OAuth token. Read more about OAuth tokens |
Bearer <access_token> |
None |
Perform hold or unhold or send dtmf or transfer on the call leg.
{
"state": "held"
}{
"state": "active"
}{
"dtmf": "*123#"
}{
"stream": true,
"stream_url": "https://example.com/recorded_message.wav"
}{
}{
"state": "active",
"to": "{'destination': Contact, 'type': ttype}"
}{
"state": "active",
"to": "{'destination': leg_id,'type': 'leg'}"
}{
"state": "active"
}{
"recording": "start",
"service": "ccr"
}{
"recording": "stop",
"service": "ccr"
}{
"recording": "start",
"service": "ocr"
}{
"recording": "stop",
"service": "ocr"
}{
"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
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
| Key | Description | Example | Default |
|---|---|---|---|
| Authorization |
Your OAuth token. Read more about OAuth tokens |
Bearer <access_token> |
None |
This endpoint does not support application/json
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
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
| Key | Description | Example | Default |
|---|---|---|---|
| Authorization |
Your OAuth token. Read more about OAuth tokens |
Bearer <access_token> |
None |
Return max this number of devices in the response.
Either ascending or descending order.
Must be one of asc or desc.
Return the devices that were registered after this point in time.
Should be of type epoch with seconds precision.
Return the devices that were registered before this point in time.
Should be of type epoch with seconds precision.
{
"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 responseGET
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
| Key | Description | Example | Default |
|---|---|---|---|
| Authorization |
Your OAuth token. Read more about OAuth tokens |
Bearer <access_token> |
None |
Mac address of device
{
"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