×
FreshBooks
Official App
Free – Google Play
Hey there - We have updated our privacy policy in accordance with GDPR. Got 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 and Time Tracking List resources allow you to perform searches. Searches are specified by appending parameters to the URL of the request. When providing a filter through the accounting endpoint you must encode the URL, while the timetracking endpoint does not require any URL encoding. 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.flashmind.info/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.flashmind.info/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 Searches (timetracking endpoint)

(Assume https://api.flashmind.info/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-01-01&started_to=2018-01-01

Example Includes

(Assume https://api.flashmind.info/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

Example Paging

(Assume https://api.flashmind.info/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.flashmind.info/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.flashmind.info/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