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:
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 |
Updated almost 4 years ago