Getting started
APIs
Business SMS
Automation
Use cases
Create Trello Card for Voicemails Received
Send Call Data to Google Sheets
Slack Notifications from Call Events
Trigger SMS Messages from Your CRM
VirtualPBX API gives you the tools to develop high-quality unified telecom applications. Our REST API interface provides a simple way for external applications to talk to VirtualPBX by making HTTP requests.
Plain Text
/{VERSION}/accounts/{ACCOUNT_ID}/resources/{RESOURCE_ID}
{VERSION}
- The version of the API you are calling.
{ACCOUNT_ID}
- Most requests operate against a specific account and thus require the account_id to route the resquest properly{RESOURCE_ID}
- When accessing a specific resource, like a device, user, or callflow, this is the {RESOURCE_ID}
points to the specific instance you're accessing.There are two parts to how a request is routed: the REST endpoint and the resource ID. Let's break down a common URI and see how Dash figures out what is an endpoint and what is a resource ID.
Given a uri of /v2/accounts/{ACCOUNT_ID}/devices/{DEVICE_ID}
:
/accounts/{ACCOUNT_ID}/devices/{DEVICE_ID}
{accounts: []}
/{ACCOUNT_ID}/devices/{DEVICE_ID}
{accounts: [{ACCOUNT_ID}]}
/devices/{DEVICE_ID}
{accounts: [{ACCOUNT_ID}], devices: []}
/{DEVICE_ID}
v2
{accounts: [{ACCOUNT_ID}], devices: [{DEVICE_ID}]}
So we have a request to account {account_id} to do something with a device {device_id}.
The HTTP verb will determine the class of actions to take against the resource. Generically speaking, the verbs map thusly:
/v2/accounts/{ACCOUNT_ID}/resources
/v2/accounts/{ACCOUNT_ID}/resources/{RESOURCE_ID}
Some resources support the PATCH verb, allowing partial updates instead of requiring the request to include the full version of the document. /users/{USER_ID}
, for instance, supports PATCH:
Plain Text
curl -v -X PATCH -H "Content-Type: application/json" -H "X-Auth-Token: {AUTH_TOKEN}" '<https://api.virtualpbx.net/v2/accounts/{ACCOUNT_ID}/webhooks/{WEBHOOKS_ID}>' -d '{"data":{"enabled":true}}'
This cURL request will patch the user's doc and set vm_to_email_enabled
to true
. All normal validation will occur after patching the document.
If a resource does not support PATCH, clients can expect to receive a 405 Method Not Allowed
error.
Some clients do not support the full range of HTTP verbs, and are typically limited to GET and POST. To access the functionalities of PUT and DELETE, you can tunnel the verb in a POST in a couple of ways:
{"data":{...}, "verb":"PUT"}
/v2/accounts/{ACCOUNT_ID}/resources?verb=PUT
Some clients do not support the ability to set the Accept header in the request, meaning they will not necessarily receive the response in the format they wish. Clients can append accept=text/html
to the request body or query string to indicate they'd like the response processed as if the Accept header was text/html
.
Note: accept=csv
is retained for backwards-compatibility but it is encouraged to use a proper media type going forward.
Most APIs require the client to have authenticated and received a token usable on subsequent requests.
When issuing a PUT or POST, a request body is needed. When submitting a JSON (the most common body), Dash expects a request envelope with a few bits of metadata:
Sample Request Envelope:
JSON
{
"data": {
"foo": "bar"
},
"auth_token": "{AUTH_TOKEN}",
"verb": "delete"
}
When receiving JSON responses, clients will receive the response in an envelope. The response includes some duplicated data from the HTTP Response headers, since some clients do not have access to those headers.
data
: contains the results of the request, if anyauth_token
: contains the auth_token used on the requeststatus
: One of 'success', 'error', or 'fatal'message
: Optional message that should clarify what happened on the requesterror
: Error code, if anyrequest_id
: ID of the request; usuable for debugging the server-side processing of the requestSample Response Envelope:
JSON
{
"data": {
"the": "response",
"data": "is here"
},
"auth_token": "{AUTH_TOKEN}",
"status": "success",
"request_id": "{REQUEST_ID}"
}
All listing APIs in v2 will be paginated by default.
Let's take a look at the CDRs API to see how to interpret pagination.
We start with the typical CDR request for a listing of CDRs:
Shell
curl -v \\
-H "X-Auth-Token: {AUTH_TOKEN}" \\
-H "Content-Type: application/json" \\
<https://api.virtualpbx.net/v2/accounts/{ACCOUNT_ID}/cdrs>
JSON
{
"auth_token": "{AUTH_TOKEN}",
"data": [
{CDR_OBJECT},
{CDR_OBJECT},
...
],
"next_start_key": 63566193143,
"page_size": 25,
"request_id": "{REQUEST_ID}",
"revision": "{REVISION}",
"start_key": 63565345339,
"status": "success"
}
The pagination response keys are next_start_key
, page_size
, and start_key
.
next_start_key
: used to get the next page of results from this API. Will not exist if this is the last page.start_key
: used to get back to this page of results (or start pagination from this point)page_size
: the number of results returned in this pageAssuming no changes are made to the underlying documents, start_key
will get you this page of results, and next_start_key
will give you a pointer to the next page (imagine a linked-list).
Using the next_start_key
value, let's request the next page of CDRs:
Shell
curl -v \\
-H "X-Auth-Token: {AUTH_TOKEN}" \\
-H "Content-Type: application/json" \\
<https://api.virtualpbx.net/v2/accounts/{ACCOUNT_ID}/cdrs?start_key=63566193143>
JSON