Batching and filters

Why batching exists

List endpoints return at most 100 entities per response. To export or sync an entire dataset you must walk batches with cursors.

Common query parameters

These parameters apply to most collection list endpoints (/companies, /debtors, /documents, /general-log-entries, and others):

Name	Required	Description
companyId	No	Limit results to one company. Ignored when cursor is set. Discover IDs via GET /companies.
modifiedSince	No	RFC 3339 timestamp. Returns entities modified at or after this time. Ignored when cursor is set.
cursor	No	Opaque cursor from a previous response (next_batch_cursor or resume_cursor). When set, companyId and modifiedSince are ignored.

Example

curl -X GET 'https://{your-collections-platform-host}/api/v1/debtors?companyId=1&modifiedSince=2024-01-01T00:00:00%2B00:00' \
    -H 'accept: application/json' \
    -H 'Authorization: Bearer <token>'

Response envelope

{
  "data": [ { "...entity..." } ],
  "next_batch_url": "https://…/api/v1/debtors?cursor=…",
  "next_batch_cursor": "…",
  "resume_url": null,
  "resume_cursor": null
}

Incremental full export

1. Call the endpoint (optionally with companyId / modifiedSince).
2. Process data.
3. If next_batch_cursor is non-empty, call again with ?cursor={next_batch_cursor}.
4. Repeat until next_batch_cursor is empty.
5. Store resume_cursor when present. Later, pass it as cursor to fetch only changes since that point.

Race window

modifiedSince cannot be more recent than 600 seconds ago. To get the newest data, use a modifiedSince at least 10 minutes in the past and walk all batches. Due to concurrent writes you may see entities you already received; you will not miss changes in the window.

Company division

In BT Collections a company is a group of debtors; each debtor belongs to exactly one company. Many calls are scoped by companyId. Start with GET /companies to list companies your token can access, then loop per company if you need a full export.