API pagination (page, per_page and cursor)

Endpoints that return lists (contacts, conversations, deals, board items, etc.) use pagination so you don't get thousands of records in a single response. Omnifox supports two styles: page-based pagination (the default) and cursor-based pagination.

Page-based pagination (default)

Parameters:

• page: page number, starting at 1.
• per_page: items per page, max 100 (default 15).

The response includes:

{
  "success": true,
  "data": [ ... ],
  "meta": { "current_page": 1, "last_page": 5, "per_page": 15, "total": 73, "from": 1, "to": 15 },
  "links": { "first": "...", "last": "...", "prev": null, "next": "..." }
}

Use links.next directly to move forward without building the URL yourself.

Cursor-based pagination

Add ?pagination=cursor to the list request. The response shape changes:

{
  "items": [ ... ],
  "pagination": {
    "next_cursor": 12345,
    "previous_cursor": 12380,
    "has_more": true,
    "limit": 20
  }
}

To request the next page, pass ?cursorId=12345 on the following call. This is the recommended mode for lists that change constantly (e.g. messages in an active conversation), because it doesn't skip or repeat records when new rows are inserted between pages.

Example: walking all contacts with a cursor

curl "https://app.omnifox.io/api/v1/contacts?pagination=cursor&limit=50" \
  -H "Authorization: Bearer YOUR_TOKEN"

# next page:
curl "https://app.omnifox.io/api/v1/contacts?pagination=cursor&limit=50&cursorId=12345" \
  -H "Authorization: Bearer YOUR_TOKEN"

Tips

• For bulk exports (thousands of records), prefer cursor pagination: page/per_page uses LIMIT/OFFSET under the hood, which gets slow on very high page numbers.
• Stop walking once has_more is false or next_cursor is null.

Troubleshooting

• Records repeat or go missing while paging with page: if the list is sorted by a field that changes (like last_message_at), new rows being inserted can shift results between pages; switch to cursor pagination.
• per_page above 100 has no effect: the maximum allowed is 100; larger values get clamped.