Pagination

Every list endpoint, like List all receivables, returns its results one page at a time. You choose how many results a page holds with limit, and you move from page to page by passing back the next_page or previous_page token from the response you already have.

curl -G https://core.sivo.com/receivables \
  -H "Authorization: $SIVO_API_KEY" \
  -d limit=2
{
  "data": [
    { "id": "inv-1043", "obligor_id": "acct-17", "currency": "USD", "...": "..." },
    { "id": "inv-1042", "obligor_id": "acct-09", "currency": "USD", "...": "..." }
  ],
  "has_more": true,
  "next_page": "eyJzIjoiY3JlYXRlZF9hdF9kZXNjIiwiZCI6Im5leHQiLCJ2IjpbIjIwMjYtMTAtMDFUMTI6MDA6MDAuMDAwWiIsImludi0xMDQyIl19",
  "previous_page": null
}

Parameters

ParameterDescription
limitOptional, default 25. The number of results to return, from 1 to 100.
pageOptional. A token from a previous response's next_page or previous_page. Omit it on the first call to start at the beginning of the list.
sortOptional. The order of the results, from the values the endpoint supports (see Sorting). Defaults to the first one, usually newest first.
expandOptional. Pass total_count to have the response count every result in the list (see Total count).

Filters, like obligor_id on receivables or metadata[...] (see Metadata), apply to every page and combine with paging as you would expect.

List response format

FieldDescription
dataThe results on this page, in list order.
has_moreWhether more results follow this page. When false, this is the last page.
next_pageA token for the page after this one, or null on the last page.
previous_pageA token for the page before this one, or null on the first page.
total_countOnly when the request sends expand=total_count: how many results the whole list holds (see Total count).

Paging through a list

To read a whole list, keep passing next_page back as page until has_more is false:

let page;
do {
  const params = new URLSearchParams({ limit: '100' });
  if (page) params.set('page', page);
  const response = await fetch(`https://core.sivo.com/receivables?${params}`, {
    headers: { Authorization: process.env.SIVO_API_KEY },
  });
  const body = await response.json();
  for (const receivable of body.data) {
    // process each receivable
  }
  page = body.next_page;
} while (page);

To go back, pass previous_page instead. A page you reach going back holds the same results it held going forward, so a "previous" button in your own UI always shows what the user saw before.

Page tokens

  • Treat tokens as opaque. Pass them back exactly as you received them. Their contents can change at any time, so never build or edit one yourself.
  • Keep the same query. A token belongs to the sort and filters of the request that returned it. Send them again unchanged with the token; a token used with a different sort is rejected with a 400 (see Errors).
  • New results don't shift your pages. A token marks a position in the list, not a count of results to skip, so results created while you page through never repeat a result or make you miss one. Newly created results appear at the start of a newest-first list, so start again from the first page to see them.

Total count

To show how many results a list holds, like "Viewing 26–50 of 1,234 results", send expand=total_count. The response then carries total_count, the number of results matching your filters across every page, not just this one:

curl -G https://core.sivo.com/receivables \
  -H "Authorization: $SIVO_API_KEY" \
  -d limit=25 \
  -d expand=total_count
{
  "data": [ "..." ],
  "has_more": true,
  "next_page": "eyJzIjoiY3JlYXRlZF9hdF9kZXNjIi...",
  "previous_page": null,
  "total_count": 1234
}
  • Exact up to 10,000. A list with more results than that reports 10001, meaning "more than 10,000", so show it as "10,000+".
  • Ask only when you need it. Counting costs an extra query, so the count is left out unless you expand it. Ask for it on the first page and keep it while paging, rather than on every page.
  • It can change as you page. The count is taken when each request runs, so results created in the meantime are included in a later page's count.

Sorting

Each list supports a short list of orders, named after the field and direction (for example origination_date_desc). Pass one as sort; any other value is rejected with a 400. Each endpoint's reference page lists the orders it supports and its default.

When two results tie on the sorted field, their order is still fixed, so paging never skips or repeats one. Results with no value for the sorted field, like a receivable whose balance hasn't been calculated yet, come last when sorting descending and first when sorting ascending.


Did this page help you?