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:

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

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:

Equals searches look for an exact match for the value.
In searches look for a match in a list, with each list item specified by its own query parameter
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”.
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.
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)
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

Example Paging

(Assume https://api.freshbooks.com/accounting/account/<accountid> precedes each line)
# return page 4 of invoices
/invoices/invoices?page=4
# return 4 invoices per page
/invoices/invoices?per_page=4
# return page 4 at 4 per page
/invoices/invoices?per_page=4&page=4
# will only return 100 invoices
/invoices/invoices?per_page=2000
# return an empty page of results (provided there aren't 200 pages)
/invoices/invoices?page=2000
# return an error about an invalid page
/invoices/invoices?page=-1

Example Searches (accounting endpoint)

(Assume https://api.freshbooks.com/accounting/account/<accountid> precedes each line)
?search[key]=value is url-encoded as ?search%5Bkey%5D=value
?search[key][]=value1&search%5Bkey%5D%5B%5D=value2 is url-encoded as ?search%5Bkey%5D%5B%5D=value1&search[key][]=value2?
?search[key1]=value1&search[key2]=value2 is url-incoded as ?search%5Bkey1%5D=value1&search%5Bkey2%5D=value2
# search for invoice 12345
/invoices/invoices?search[invoiceid]=12345
# search for invoices 123 and 124
/invoices/invoices?search[invoiceids][]=123&search[invoiceids][]=124
# search for invoice created before 2016-09-01
/invoices/invoices?search[date_max]=2016-09-01
# search for invoice created between 2016-08-01 and 2016-09-01
/invoices/invoices?search[date_min]=2016-08-01&search[date_max]=2016-09-01

# search for clients with outstanding amounts
/users/clients?search[has_overdue]=true
# search for compound taxes I have saved
/taxes/taxes?search[compound]=true

Example Searches (timetracking endpoint)

(Assume https://api.freshbooks.com/timetracking/business/<businessid> precedes each line)
# search for incompleted projects
/projects?complete=true
# search for projects updated since a specified date
/projects?updated_since=2017-07-12T15:00:53
# search for projects that are still active
/projects?active=true
# search for time entries that are billed (attached to an invoice)
/time_entries?billed=true
# search for time entries between two given dates
/time_entries?started_from=2017-07-12T15:00:53&started_to=2017-07-13T15:00:53

Example Includes

(Assume https://api.freshbooks.com/accounting/account/<accountid> precedes each line)
?include[]=value is the pattern, url-encoded as ?include%5B%5D=value
# include lines inline with invoice
/invoices/invoices?include[]=lines
# include list of allowed gateways on invoice
/invoices/invoices?include[]=allowed_gateways
# include both lines and allowed gateways on invoice
/invoices/invoices?include[]=lines&include[]=allowed_gateways
# include invoice information on payment
/payments/payments?include[]=invoice

Example Sort (accounting endpoint)

(Assume https://api.freshbooks.com/accounting/account/<accountid> precedes each line)
?sort=field_name_[asc|desc] is the pattern

# sort invoice by date ascending (eg. 2022-01-19, 2022-02-24)
/invoices/invoices?sort=invoice_date_asc
# sort invoice by date descending (eg. 2022-02-24, 2022-01-19)
/invoices/invoices?sort=invoice_date_desc

Example Sort (project endpoint)

(Assume https://api.freshbooks.com/projects/business/<businessid> precedes each line)

# sort project by due date ascending (eg. 2022-01-19, 2022-02-24)
/projects?sort=due_date
# sort project by date descending (eg. 2022-02-24, 2022-01-19)
/projects?sort=-due_date