Pagination and cursors

Lists return a list envelope:

{
  "object": "list",
  "data": [ { "object": "entity", "…": "…" } ],
  "has_more": true,
  "next_cursor": "eyJ2IjoxLCJzb3J0Ijoi…",
  "data_as_of": "2026-10-19"
}

To get the next page, send the same parameters again with cursor=<next_cursor>:

curl "https://api.maticna.si/v1/entities?q=cebelica&cursor=eyJ2IjoxLCJzb3J0Ijoi…" \
  -H "Authorization: Bearer $MATICNA_KEY"

Rules

• The cursor is opaque and signed with HMAC. Do not parse or modify it; a modified cursor returns 400 bad_request.
• The cursor is bound to the query. If you change q or the filters, start without a cursor.
• The cursor is bound to the data version. When the data is refreshed daily (X-Data-Version changes), an old cursor returns 409 cursor_expired. Start again from the first page.
• A filtered list is ordered by tax number (keyset); a relevance search by (score, id).

Depth limit

One query returns at most 1,000 results (20 pages of 50) for legal entities and 50 for natural persons. Once the limit is reached, has_more is false. Narrow the filters (e.g. postal_code, activity_code).

For the full set of legal entities, use the daily exports on the Custom plan, not pagination. Natural persons are not exported.

Pattern

async function* all(params) {
  let cursor;
  for (;;) {
    const qs = new URLSearchParams({ ...params, ...(cursor ? { cursor } : {}) });
    const r = await fetch(`https://api.maticna.si/v1/entities?${qs}`, { headers });
    if (r.status === 409) { cursor = undefined; continue; } // data refreshed: start over from page 1 (dedupe already received rows by tax_number if needed)
    if (!r.ok) throw new Error(`maticna.si ${r.status}`);
    const page = await r.json();
    yield* page.data;
    if (!page.has_more) return;
    cursor = page.next_cursor;
  }
}