Endpoints which return a list of objects are paginated. Most use page-based pagination; a few newer endpoints use a cursor, and one uses an offset. Each endpoint's reference page lists the parameters it accepts.

Page-based pagination

This is the common standard, used for example by Get Settlements.

Request

When making a GET request, you can specify the following query parameters to control the response:

• page - the page number to return, starting at 1 (default: 1);
• pageSize - the maximum number of objects to return per page (default and maximum: 30).

For example, the following request would return 30 results, skipping the first 30 on page 1:

GET /v1/settlements?page=2&pageSize=30

Response

In the response there is a meta object which contains the following details:

• page - the page number returned
• pageSize - the maximum number of objects per page
• total - the total number of objects

The structure of the meta object is:

"meta": {
  "pagination": {
    "page": 2,
    "pageSize": 30,
    "total": 250
  }
}

Retrieving every page

Calculate the number of pages from total and pageSize — here, 250 objects at 30 per page is 9 pages — and request each page in turn.

🚧

A page past the last one returns 404

Requesting a page other than the first that yields no results returns a 404 error rather than an empty list. Stop at the calculated last page, and treat a 404 on a later page as the end of the list. The first page always returns 200, with an empty data array when there is nothing to list.

Cursor-based pagination

A few endpoints return pages through an opaque cursor: List invoices, List intakes, List Analytical Field Values and List Expense Categories.

Request

• limit - the maximum number of objects to return per page. The default and maximum differ per endpoint (for example 20 and 100 for invoices, 30 and 1,000 for analytical field values) — see each endpoint's reference;
• cursor - omit it for the first page, then pass the nextCursor value from the previous response. Keep the same filters and sort for every page.

Response

"meta": {
  "pagination": {
    "limit": 50,
    "hasNextPage": true,
    "nextCursor": "eyJvZmZzZXQiOjUwfQ",
    "nextUrl": "https://public-api.spendesk.com/v2/companies/7j6mvn11rqf7j5/invoices?limit=50&cursor=eyJvZmZzZXQiOjUwfQ"
  }
}

• hasNextPage - whether more results exist after this page;
• nextCursor - the cursor to pass for the next page, or null when there are no more results;
• nextUrl - a ready-to-follow URL for the next page, with the same filters and the cursor already set, or null.

Keep requesting pages until hasNextPage is false. Unlike page-based pagination, a page may legitimately be empty — it is not an error.

Searching payables

Search payables takes cursor and limit in the request body rather than the query string, and returns the next cursor as a top-level nextCursor field: send it back in the next request's body, and stop when it is null.

Offset-based pagination

Get accounts pages with offset (the number of accounts to skip, default 0) and fetch (the number of accounts to return); limit is deprecated in favour of fetch. The response reports totalResults, currentOffset and currentFetch.

Payable snapshots

Snapshots of payables are paged inside their result object — see Retrieving Spend Data.