Pagination
Cursor pagination, page size and syncing with updated_since.
Developer documentation
List endpoints are paginated. The response always comes in the same envelope:
{ "data": [], "next_cursor": null }
limit: the page size. 25 by default, at most 100; a larger value is lowered to the maximum.next_cursor: the cursor of the next page. It isnullon the last page.cursor: thenext_cursorvalue of the previous response. The cursor is opaque and signed: do not try to read or change it. Send it with the same key (or its rotated successor) and the same filter; if the filter changes you get400 cursor_invalid. A cursor lives for 3 days.- No total count is returned.
Order
Lists are ordered by ID and the order is stable: no record is skipped or repeated between pages. There is no sort parameter; ID order does not mean "newest first".
Syncing: updated_since
The employee, leave request and shift assignment lists take the updated_since filter: only records whose updated_at is greater than or equal to the given moment are returned.
- The value is an ISO 8601 moment with a time zone (
2026-06-16T08:00:00Z); a bare day gets400. - The filter is inclusive: send the last
updated_atyou saw and deduplicate records by ID. - An employee's classified fields (national ID, IBAN, salary, personal details) are stored separately and their changes do not move
updated_at. If you sync those fields, read the record again. - A deleted shift assignment or an unpublished plan does not show up through
updated_since; theshift.assignment.changedandshift.plan.publishedevents report it (Event catalogue).
Example: walking all employees
CURSOR=""
while :; do
curl -sS "$BIIK_API_URL/api/v1/employees?limit=100${CURSOR:+&cursor=$CURSOR}" \
-H "Authorization: Bearer $BIIK_API_KEY" > page.json
jq -r '.data[].id' page.json
CURSOR=$(jq -r '.next_cursor // empty' page.json)
[ -z "$CURSOR" ] && break
done
cat page.json
Expected response: 200 Successful
Example response (from the OpenAPI document)
{
"data": [
{
"id": "3f2b1c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"company_id": "0b8f6c1e-5f0a-4c7e-9a43-2f6f3a1d9c10",
"org_unit_id": "c4a1e2b3-7d6f-4e5a-9b8c-1f2e3d4c5b6a",
"job_title_id": "9e7d6c5b-4a39-4821-8f70-6e5d4c3b2a19",
"position_id": null,
"manager_id": null,
"first_name": "Deniz",
"last_name": "Kaya",
"work_email": "[email protected]",
"status": "active",
"employment_type": "full_time",
"hire_date": "2026-03-02",
"service_start_date": null,
"sgk_entry_date": null,
"probation_end": "2026-05-02",
"is_demo": false,
"created_at": "2026-02-24T09:30:00.000Z",
"updated_at": "2026-03-02T07:00:00.000Z"
}
],
"next_cursor": null
}