--- notionId: "670ef73b7a304f908bdcd9cc4127b8d8" product: "developer" cluster: "start" intent: "developer.api-basics" docSlug: "api-basics" task: "API Basics in the API" title: "API Basics in the API | VirtualPBX" meta_description: "The Dash API is a REST interface that external applications call with ordinary HTTP requests. A request names a resource and an action, and the URI splits into" answer: "The Dash API is a REST interface that external applications call with ordinary HTTP requests. A request names a resource and an action, and the URI splits into the endpoint plus the resource id so Dash can route it. The same API covers the verbs those requests use, including PATCH and the tunneled form of a verb when a client cannot send it directly. Start with this page before calling a specific resource." audience: "user" updated: "2026-09-29" legacy: ["api-basics"] headings: [{"depth":2,"text":"Introduction","id":"introduction"},{"depth":3,"text":"Basic URI Structure","id":"basic-uri-structure"},{"depth":3,"text":"Resources","id":"resources"},{"depth":3,"text":"HTTP Verbs","id":"http-verbs"},{"depth":3,"text":"PATCH","id":"patch"},{"depth":3,"text":"Tunneling the HTTP Verb","id":"tunneling-the-http-verb"},{"depth":3,"text":"Tunneling the Accept Header","id":"tunneling-the-accept-header"},{"depth":3,"text":"Authentication Tokens","id":"authentication-tokens"},{"depth":3,"text":"Request Envelope","id":"request-envelope"},{"depth":3,"text":"Response Envelope","id":"response-envelope"},{"depth":3,"text":"Pagination","id":"pagination"},{"depth":3,"text":"API Pagination","id":"api-pagination"},{"depth":3,"text":"Requesting a page","id":"requesting-a-page"},{"depth":3,"text":"Disabling Pagination","id":"disabling-pagination"},{"depth":3,"text":"Requesting a range of binary data","id":"requesting-a-range-of-binary-data"},{"depth":2,"text":"Query String Filters","id":"query-string-filters"},{"depth":3,"text":"How filters limit results","id":"how-filters-limit-results"},{"depth":3,"text":"Available Filters","id":"available-filters"},{"depth":3,"text":"Keys","id":"keys"},{"depth":3,"text":"Multiple Filters","id":"multiple-filters"}] lint: [] --- ## 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}

{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.

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

First, strip the version off the URI
See if the next token is a REST endpoint module. It is, so track the module for later routing:
See if the next token is a REST endpoint module. It is not, so add the token to the last module's data:
Repeat parsing. devices is a REST endpoint:
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:

/v2/accounts/{ACCOUNT_ID}/resources
/v2/accounts/{ACCOUNT_ID}/resources/{RESOURCE_ID}

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

As part of the request envelope: {"data":{...}, "verb":"PUT"}
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](http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html) 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`. ### Authentication Tokens Most APIs require the client to have authenticated and received a token usable on subsequent requests.

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:

data: this top-level key will contain the object you wish to create/update
auth_token: optionally put your auth token in the envelope
verb: optionally tunnel a PUT or DELETE in a POST request

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.

data: contains the results of the request, if any
auth_token: contains the auth_token used on the request
status: One of 'success', 'error', or 'fatal'
message: Optional message that should clarify what happened on the request
error: Error code, if any
request_id: ID of the request; usuable for debugging the server-side processing of the request

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 recordings API to see how to interpret pagination. ### API Pagination We start with the typical recordings request for a listing of recordings: Shell

curl -v \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    -H "Content-Type: application/json" \
    https://api.virtualpbx.net/v2/accounts/{ACCOUNT_ID}/recordings

JSON

{
    "auth_token": "{AUTH_TOKEN}",
    "data": [
        {RECORDING_OBJECT},
        {RECORDING_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 page

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 recordings: Shell

curl -v \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    -H "Content-Type: application/json" \
    https://api.virtualpbx.net/v2/accounts/{ACCOUNT_ID}/recordings?start_key=63566193143

JSON

{
    "auth_token": "{AUTH_TOKEN}"
    "data": [
        {RECORDING_OBJECT},
        {RECORDING_OBJECT},
        ...
    ],
    "next_start_key": 63566542092,
    "page_size": 25,
    "request_id": "{REQUEST_ID}",
    "revision": "{REVISION}",
    "start_key": 63566193143,
    "status": "success"
}

Observe now that `start_key` is the requested `start_key` and `next_start_key` points to the start of the next page of results. If `next_start_key` is missing from the response envelope, the response represents the last page of results. You can also choose to receive pages in bigger or smaller increments by specifying `page_size` on the request. Do take care, as the `next_start_key` will probably vary if you use the same `start_key` but differing `page_size` values. ### Disabling Pagination If you want to disable pagination for a request, simply include `paginate=false` on the query string. ### Requesting a range of binary data It is useful to be able to get just a section of a file when streaming or resuming a download. This can be accomplished with the range header, eg: Shell

curl -v \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    -H "Content-Type: application/json" \
    -H "Accept: audio/mpeg" \
    -H "Range: bytes={START_BYTE}-{END_BYTE}" \
    https://api.virtualpbx.net/v2/accounts/{ACCOUNT_ID}/vmboxes/{VMBOX_ID}/messages/{MESSAGE_ID}/raw

## Query String Filters ### How filters limit results Query string filters allow the API results to be filtered by additional criteria to limit the result set. This is especially useful when querying a collection that could be massive (like recordings) but you're only interested in results that match certain criteria. ### Available Filters

Filter	Operates On	Description
`filter_not_{KEY}`	`{VALUE}`	Doc include if `{KEY}` is not `{VALUE}`
`filter_{KEY}`	`{VALUE}`	Doc included if `{KEY}` is `{VALUE}`
`has_key`	`{KEY}`	Doc included if `{KEY}` is present on the doc
`key_missing`	`{KEY}`	Doc included if `{KEY}` is not present on the doc
`has_value`	`{KEY}`	Doc included if `{KEY}` exists and the `{VALUE}` is non-empty
`missing_value`	`{KEY}`	Doc included if `{KEY}` is not present or the `{VALUE}` is empty
`created_from`	`{VALUE}`	Doc included if the created time is greater than or equal to `{VALUE}` (in Gregorian seconds)
`created_to`	`{VALUE}`	Doc included if the created time is less than or equal to `{VALUE}` (in Gregorian seconds)
`modified_from`	`{VALUE}`	Doc included if the last-modified time is greater than or equal to `{VALUE}` (in Gregorian seconds)
`modified_to`	`{VALUE}`	Doc included if the last-modified time is less than or equal to `{VALUE}` (in Gregorian seconds)

### Keys Filters can be used on validated keys (those appearing in the schema) and on custom keys (those included by the caller). `{KEY}` can be a dot-delimited string representing a JSON key path. So `filter_foo.bar.baz=1` would match a doc that had `{"foo":{"bar":{"baz":1}}}` in it. ### Multiple Filters Filters can be chained together on a query string and will be applied as a boolean `AND` operation. For example, `?filter_foo=1&has_key=bar` will look for docs where `foo=1` and the key `bar` exists on the doc.