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

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

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.
• There is no total count. Lists don't report how many results they hold or let you jump to a page number; use filters to narrow a list instead.

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.

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.

Deprecated parameters

Lists used to page with skip and take, or with an id to start after. Lists ignore these parameters now and return the first page; use limit and page instead.

The two transparency lists, GET /transparency/transactions and GET /transparency/balances, still honor skip and take so existing integrations keep working: a request that sends either one is paged by offset as before, with take defaulting to 100 and capped at 1,000, and its response carries no page tokens. Without them, the transparency lists page with limit and page like every other list, with limit defaulting to 100. Move to limit and page; skip and take will be removed in a future version of the API.