×
Freshbooks
Official App
Free – Google Play
Get it

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 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.

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.

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

(Assume https://api.freshbooks.com/accounting/account/<accountid> precedes each line)

?search[key]=value is url-encoded as ?search%5Bkey%5D=value

# search for invoice 12345
/invoices/invoices?search%5Binvoiceid%5D=12345
# search for invoices 123 and 124
/invoices/invoices?search%5Binvoiceids%5D=123&search%5Binvoiceids%5D=124
# search for invoice created before 2016-09-01
/invoices/invoices?search%5Bdate_max%5D=2016-09-01
# search for invoice created betwteen 2016-08-01 and 2016-09-01
/invoices/invoices?search%5Bdate_min%5D=2016-08-01&search%5Bdate_max%5D=2016-09-01
# search for clients with outstanding amounts
/users/clients?search%5Bhas_overdue%5D=true
# search for compound taxes I have saved
/taxes/taxes?search%5Bcompound%5D=true

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%5B%5D=lines
# include list of allowed gateways on invoice
/invoices/invoices?include%5B%5D=allowed_gateways
# include both lines and allowed gateways on invoice
/invoices/invoices?include%5B%5D=lines&include%5B%5D=allowed_gateways
# include invoice information on payment
/payments/payments?include%5B%5D=invoice