Inputs

Many of our API services represent lists of objects, such as accounts, extensions, and phone numbers. Unless noted otherwise, they all follow common conventions for sorting, filtering, and pagination. These features are described below.

Pagination

Because many lists can be quite long, we feature two inputs to help with pagination: limit and offset. These have the same meanings as used in many database engines and popular APIs:

For example, say we are working with the List Extensions service. To retrieve only the first 5 results, we would add limit=5 as a query argument, like so:

/accounts/123/extensions?limit=5

To skip the first 15 results, we would add offset=15 as a query argument, as follows:

/accounts/123/extensions?offset=15

These parameters can be combined to provide robust pagination functionality. The above two examples together would produce a paginated result set with 5 items per page, showing the 4th page of results:

/accounts/123/extensions?limit=5&offset=15

Sorting

Many services provide the ability to sort the result set in various ways. Check the documentation for each one to determine which fields are sortable. Sorting is specified with the following syntax:

sort[<field>]=(asc|desc)

For example, to sort a List Extensions response by ID ascending, your query would look like this:

/accounts/123/extensions?sort[id]=asc

Note that this syntax allows for sorting by multiple fields. This can be useful for more complicated result sets which we will not explain at this time. If multiple sort parameters are present, they will be applied from left to right.

Fields Returned

By default, services include a full representation of each item in the result set. But if all you need is a list summarizing the results that were found, you can use the fields property to request an abbreviated version:

fields=brief

If for some reason you need to explicitly request the full representation, you can use either of these instead:

fields=all
--or--
fields=full

Filtering

Many services also allow filtering the result set. Check the documentation for each one to determine which fields can be used as filters. Any number of filters are supported, and multiple filters can be specified for the same field. Most filters allow using a very extensive range of operators too (described below.)

Syntax of Filters

There are several supported filter syntaxes. First we demonstrate the simplest filter, which uses the implied eq operator to retrieve all results where <field> exactly equals <value>:

filters[field]=value

For example, to filter call logs List Call Logs response by call type, your query would look like this:

/accounts/123/call-logs?filters[type]=call

Other operators are specified by concatenating the operator and the value with a colon, as follows:

filters[field]=operator:value
Example:  /accounts/123/call-logs?filters[type]=eq:call

Multiple filters can be used on the same field, as follows. This is useful for advanced querying with operators other than eq:

filters[field]=operator1:value1&filters[field]=operator2:value2
Example:  /accounts/123/call-logs?filters[type]=call&filters[start_time]=gt:6789&sort[start_time]=asc

Some operators such as empty don't accept any values. In this case, the colon and the value are omitted from the query:

filters[field]=operator
Example:  filters[name]=not-empty

Some operators such as in accept multiple values. Use a comma-separated list in these cases:

filters[field]=operator:value1,value2,value3
Example: filters[npa]=in:732,201,917

Operators

Here are the filter operators supported by most of our list-based services. Note that some services only support a subset of operators. Check the documentation for each service to be sure.