Sign in
Start free7-day free trial
Live API contract
Start here

Pagination and list processing

Use cursor pagination only where the endpoint declares it, and keep long-running record synchronization restartable.

Some list endpoints expose limit and cursor parameters. Check the specific reference before adding them. For example, listing templates is not the same contract as searching a large waiver collection.

Follow the returned cursor

For endpoints that declare cursor pagination, the default page size is 25 and the allowed size is 1 through 100. Read the page's nextCursor. A null value means there is no next page for that result set.

Treat a cursor as an opaque value. Do not decode it, invent the next value or substitute a record ID because the two happen to look similar. Preserve the same filter choices while walking a result set.

Save progress after durable work

Process a page into your database or queue, then save the next cursor. If the worker restarts, resume from the last durable checkpoint. Saving the cursor before storing the records can skip a page after a crash.

A repeated page should not create duplicate rows in your destination. Upsert by the source record ID and keep your synchronization bookkeeping separate from participant attributes. This also helps when a job is restarted deliberately.

Understand what a list does not guarantee

A cursor is not a promise that the underlying collection is frozen. New signatures or updates can occur while a long synchronization is running. Choose a reconciliation strategy appropriate to your application and use event notifications for ongoing changes.

Do not apply one universal response parser to every list route. A participant response, event response and webhook delivery response can have different fields. Use the published response schema for each resource.

Test the boundary cases

Try an empty result, a single page, an exact page-size result and several pages. Confirm the job stops on null and does not keep polling the final cursor. Then simulate a restart between storing data and advancing the checkpoint.

Start with waiver search or participant search, and pair the initial import with the webhook overview for subsequent changes.