Getting started

Getting Started

API Basics

APIs

Authentication

Blocklists

Call Channels

Call Center

Call Recordings

Devices

Pivot

Quickcall

Webhooks

Business SMS

VirtualText

Automation

Zapier

Use cases

Create Trello Card for Voicemails Received

Send Call Data to Google Sheets

Slack Notifications from Call Events

SMS Airtable Template

Trigger SMS Messages from Your CRM

Zapier Webinar Recording

Introduction

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.

Basic URI Structure

Plain Text

/{VERSION}/accounts/{ACCOUNT_ID}/resources/{RESOURCE_ID}

Resources

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}:

  1. First, strip the version off the URI
  2. See if the next token is a REST endpoint module. It is, so track the module for later routing:
  3. See if the next token is a REST endpoint module. It is not, so add the token to the last module's data:
  4. Repeat parsing. devices is a REST endpoint:
  5. Repeat parsing. {DEVICE_ID} is an argument:

So we have a request to account {account_id} to do something with a device {device_id}.

HTTP Verbs

The HTTP verb will determine the class of actions to take against the resource. Generically speaking, the verbs map thusly:

PATCH

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.

Tunneling the HTTP Verb

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:

  1. As part of the request envelope: {"data":{...}, "verb":"PUT"}
  2. As a query string parameter: /v2/accounts/{ACCOUNT_ID}/resources?verb=PUT

Tunneling the Accept Header

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.

Noteaccept=csv is retained for backwards-compatibility but it is encouraged to use a proper media type going forward.

Authentication Tokens

Most APIs require the client to have authenticated and received a token usable on subsequent requests.

  1. User Authentication: This is the preferred way of authenticating a user and useful for making an UI

Request Envelope

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

Response Envelope

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.

Sample Response Envelope:

JSON

{
    "data": {
        "the": "response",
        "data": "is here"
    },
    "auth_token": "{AUTH_TOKEN}",
    "status": "success",
    "request_id": "{REQUEST_ID}"
}

Pagination

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.

CDR 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_keypage_size, and start_key.

Assuming 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).

Requesting a page

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