Pagination

limit & offset

Most list endpoints accept limit (default 50, max 200) and an optional offset. The response is a JSON object whose first key is the resource collection — e.g. contacts or deals.

curl "https://app.contactfollowup.com/api/contacts?limit=100&offset=200" \
  -H "Authorization: Bearer $HEARTHNOTE_TOKEN"

{
  "contacts": [
    { "id": "cln…", "firstName": "Avery", "lastName": "Liu", "lifecycle": "PATIENT" }
  ]
}

Cursor-based

Some endpoints (notably the audit log and large-page reads coming soon) use cursors. The response body adds a nextCursor field; pass it back as the cursor query parameter to fetch the next page. When nextCursor is nullyou've reached the end.

curl "https://app.contactfollowup.com/api/audit?limit=200&cursor=2026-05-18T14:00:00Z_abcdef" \
  -H "Authorization: Bearer $HEARTHNOTE_TOKEN"

Patterns we don't use

• No Link response header. The pointer lives in the response body.
• No page numbers. Page numbers drift when records are inserted; offset is honest about being a row count.
• No embedded counts on list responses. Use the dedicated count endpoints where available (coming in v1.1).