Skip to content

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 is null on the last page.
  • cursor: the next_cursor value 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 get 400 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 gets 400.
  • The filter is inclusive: send the last updated_at you 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; the shift.assignment.changed and shift.plan.published events 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
}