Insolvency API guide

Pagination

Lists come a page at a time: by page number, or by cursor for long runs.

By page or by cursor

Every list takes a page from 1 and a cursor. Send one; if both are sent, page wins. limit sets the page size: 25 if left out, up to 25 on Developer and 100 on paid plans.

A page call returns in meta: count, page, limit, total, total_exact, total_pages, next_page, prev_page and next_cursor. A cursor call returns only count and next_cursor, so long runs stay fast. When next_cursor is null, you have everything.

Totals are counted up to 100,000. Past that, total is 100,000, total_exact is false and total_pages is null; next_page and next_cursor still take you on.

curl PHP Python JavaScriptCopy

Every page

# The first page, then follow next_cursor until it is null
$ curl "https://api.insolvencyapi.com/v1/cases?country=gb&limit=100" \
    -H "X-API-Key: $INSOLVENCY_KEY"
$ curl "https://api.insolvencyapi.com/v1/cases?country=gb&cursor=NEXT_CURSOR" \
    -H "X-API-Key: $INSOLVENCY_KEY"

$url = 'https://api.insolvencyapi.com/v1/cases?country=gb&limit=100';
while ($url) {
  $ch = curl_init($url);
  curl_setopt_array($ch, [CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => ['X-API-Key: ' . getenv('INSOLVENCY_KEY')]]);
  $page = json_decode(curl_exec($ch), true);
  foreach ($page['data'] as $case) { /* keep it */ }
  $next = $page['meta']['next_cursor'];
  $url = $next ? 'https://api.insolvencyapi.com/v1/cases?country=gb&cursor=' . $next : null;
}

import os, requests

url, params = "https://api.insolvencyapi.com/v1/cases", {"country": "gb", "limit": 100}
while True:
    page = requests.get(url, params=params, headers={"X-API-Key": os.environ["INSOLVENCY_KEY"]}).json()
    for case in page["data"]:
        pass  # keep it
    if not page["meta"]["next_cursor"]:
        break
    params = {"country": "gb", "cursor": page["meta"]["next_cursor"]}

let q = "country=gb&limit=100";
while (q) {
  const res = await fetch("https://api.insolvencyapi.com/v1/cases?" + q, { headers: { "X-API-Key": process.env.INSOLVENCY_KEY } });
  const { data, meta } = await res.json();
  for (const c of data) { /* keep it */ }
  q = meta.next_cursor ? "country=gb&cursor=" + meta.next_cursor : null;
}

Only what changed

To keep your own copy current, send updated_since with the day of your last run. You get new cases and every case with something new since, and nothing else.

Lists are ordered by each case’s latest step, newest first. A case that moves on during a long walk can shift by a place, so finish with one more run using updated_since.