Pagination, Filtering, and Cursors: How the unLocked CRM API Handles Large Result Sets

Cursor-based pagination, sparse fieldsets, range filters, and 'include' expansions — the four primitives that make our list endpoints fast at 10 contacts and…

Every CRM eventually has to answer "give me everything that matches X." How that question is asked and answered is the difference between an API that scales and one that times out at 10,000 records. Here's how unLocked CRM handles it.

Cursor-Based Pagination (Not Offset)

Every list endpoint accepts limit (max 200) and cursor. The response includes data, next_cursor (null when exhausted), and has_more. Cursor pagination is stable under concurrent writes — you'll never see the duplicate-or-skip artifacts that plague offset pagination.

GET /contacts?limit=100&cursor=eyJpZCI6...

Filtering With Operators

Filters use the bracket syntax familiar from JSON:API:

GET /contacts?filter[created_at][gte]=2025-01-01
            &filter[lead_source][in]=facebook,google
            &filter[has_policy]=false

Supported operators: eq, neq, gt, gte, lt, lte, in, nin, like, null.

Sparse Fieldsets

Pull only what you need to keep payloads small:

GET /contacts?fields=id,first_name,last_name,email

Include Expansions

Avoid the N+1 trap by expanding related resources inline:

GET /contacts/123?include=policies,opportunities,tags

Sorting

GET /contacts?sort=-created_at,last_name

Prefix with - for descending. Multiple sort keys are comma-separated.

The Net Effect

The same /contacts endpoint serves a 10-contact dashboard widget and a 10-million-row nightly export. No special "bulk" routes, no separate "search" endpoint, no surprises.