All .list methods, such as invoice.list, client.list etc, may not return the entire list of objects in a single request. If the list contains more than 25 items (by default, see ‘Page Size’ below), it will be paginated (i.e. split across multiple pages of data, each requiring a separate request to fetch).
The pagination details are included in the response to any .list method request. The response will indicate:
- Which page of data is being returned (1,2,3 etc)
- The size of the page being returned (25 by default)
- The total number of pages available at this size
- The total number of individual items available
Here’s an example response from the recurring.list method:
<response xmlns="https://www.freshbooks.com/api/" status="ok"> <recurrings page="1" per_page="25" pages="4" total="99"> <recurring> ...
The above indicates that there are 4 pages of about 25 items (the last page will be the remainder, so it may not be a full page), and a total of 99 items.
Requesting specific pages
Specific pages are requested by including a <page> element in the request with the page number you’re requesting:
<?xml version="1.0" encoding="utf-8"?> <request method='invoice.list'> <page>2</page> </request>
You can adjust the size of pages to meet your needs. The default page size is 25, but the system will allow pages of up to 100 items. (Specifying more than 100 will behave the same as if you’ve requested exactly 100). You set the page size by sending the <per_page> element with your request:
<?xml version="1.0" encoding="utf-8"?> <request method='invoice.list'> <per_page>50</per_page> </request>
If there are fewer items than the page size in the system, then the entire list is returned.
When submitting a request for the second or subsequent pages of data, make sure you specify the same value for <per_page> in each request, or you will end up with a non-contiguous list.
Things to remember
This applies to all .list methods.
All data is potentially volatile. Items can be added or removed between requests for pages of data, so there’s no absolute guarantee that items won’t be missed or duplicated when paginating over a large list, especially if a lot of time elapses between requests.