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:

Property

Data Type

Description

limit

Integer

Maximum number of objects to return in this page of results

offset

Integer

Number of objects to skip in the result set

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 exactly equals :

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.

Operator

Description and Example

empty

Empty field. Includes values of 0, empty string, or null. filters[name]=empty

not-empty

Non-empty field. filters[name]=not-empty

eq

Equal to the value. filters[id]=eq:7890

ne

Not equal to the value. filters[id]=ne:7890

lt

Less than the value. filters[year]=lt:2010

gt

Greater than the value. filters[year]=gt:2010

lte

Less than or equal to the value. filters[year]=lte:2010

gte

Greater than or equal to the value. filters[year]=gte:2010

starts-with

String begins with the value. filters[name]=starts-with:Fred

ends-with

String ends with the value. filters[name]=ends-with:Smith

contains

String contains the value. filters[name]=contains:Acme

not-starts-with

String doesn't begin with the value. filters[name]=not-starts-with:Fred

not-ends-with

String doesn't end with the value. filters[name]=not-ends-with:Smith

not-contains

String doesn't contain the value. filters[name]=not-contains:Acme

between

Number is within a range. filters[year]=between:2005,2010

not-between

Number isn't within a range. filters[year]=not-between:2005,2010

in

Value is in a given list. filters[npa]=in:402,909,316

not-in

Value isn't in a given list. filters[npa]=not-in:402,909,316

only

Combine with the deleted filter, to list only deleted items.
filters[deleted]=only

ignore

Combine with the deleted filter, to list only existing item.
filters[deleted]=ignore

with

Combine with the deleted filter, to list both deleted and existing items.
filters[deleted]=with