Search, Paging and Includes

Paging

Many calls made to our API will result in multiple pages of data. To better manage responses, we have implemented pagination. We’ve built in default limit on results per page. We recommend you always set a limit parameter so that you will know how many results to expect.

Details:

1. per_page is silently capped at 100
2. requesting page 0 will return page 1
3. requesting a non-positive-integer page will return an error indicating that page must be a number
4. requesting a page beyond the last calculated page will return an empty list of items.

Search Filters

Most Accounting and Time Tracking List resources allow you to perform searches. Searches are specified by appending parameters to the URL of the request. You can see some examples in the code section to the right.

Multiple searches can be at once by adding multiple search parameters.

The parameters that apply to each resource differ, so we’ve included a list of the applicable searches in each resource in the API Reference. In general searches follow a few common patterns:

1. Equals searches look for an exact match for the value.
2. In searches look for a match in a list, with each list item specified by its own query parameter
3. Like searches look for a match contained within the field being searched. For example, “leaf” will Like-match “aleaf” and “leafy”, but not “leav”, and “leafs” would not Like-match “leaf”.
4. Between searches indicate that both a maximum and a minimum can be specified on a given key. Maximums will match things below the value supplied, and minimums will match values equal to or greater than the value supplied.

   A special note about Betweens applied to date-time columns like “updated”: these generally only have day-level granularity, and take the input form YYYY-MM-DD.

5. Datetime searches look for entries that come before or after a particular time, as specified by the field. Eg. “updated_since” on Time Entries will return time entries updated after the provided time. The time provided must be in ISO 8601 format (eg. 2010-10-17T05:45:53Z) 
6. Bool searches look for if the boolean field is equal to true or false

Includes

Many of our resources have relations to data that requires additional calls for us to full out — calls to the API must explicitly request the inclusion of these resources, using what we call includes. Includes are specified in a very similar manner to searches — you can see some examples in the code section on the right.

As with searches, multiple includes can be applied at once by adding multiple include parameters to a URL

Again, as with searches, the parameters that apply to each resource differ, so we’ve included a list of the applicable includes in each resource in the API Reference.

Sorting

Many of our List resources allow you to sort the results by particular fields rather than the default order they are returned in. The fields that a resource supports sorting by are documented in each resource. The form of the sort differs slightly between /accounting endpoints and project-like endpoints (eg. /projects, /timetracking, /comments. See examples in the side bar.

• For accounting endpoints, to sort by a field in ascending order, use: ?sort=field_name_asc. To sort in descending order, use: ?sort=field_name_desc
• For project-like endpoints, to sort by a field in ascending order, use: ?sort=fiend_name and to sort in descending order, use ?sort=-field_name