Recipes

Poll for new companies

Pulling newly identified companies into your own systems is straightforward at first. Once traffic grows or you start managing multiple accounts, you'll want a sturdier approach. Here are the patterns we use.

Companies are created as visitors are matched. You poll on your own cadence — each call returns companies that have been created since your last sync.

Basics

One endpoint, four parameters, one timestamp to remember. Each cycle, fetch identifications since your last cursor and save the latest inserted_time from the response as the cursor for next time.

GET /v1.3/companies

Parameter	Value	Why
`sort_by`	`inserted_date`	Walk in insertion order.
`sort_order`	`asc`	Oldest first — advance the cursor in step.
`inserted_date`	`<cursor>: (range syntax)`	First-time identifications since last cycle. Empty on first run.
`limit`	`50`	Default. Raise it for higher volume — see Pagination.

Cycles

Match the cadence to your traffic.

Traffic	Cadence
20–50 sessions / day (≤ ~100)	`every 30–120 minutes`
Higher volume	`every 5–15 minutes`
Near-real-time use cases	`every 1–5 minutes`

Heads-up

Matching doesn't wait for the visit to end. A visitor may still be on your site at the moment their company match is recorded — and shows up in your next poll while the session is live. Workflows that act on a match should handle currently here as well as was here earlier.

Pagination

When response.found exceeds limit, paginate. Walk page=1, 2, 3 … until a response comes back empty before you save the cursor.

Parameter	Value
`limit`	`50` (or higher if you process larger batches)
`page`	`1, 2, 3 …` until the response is empty

Save the cursor only after the last page returns empty — otherwise a crash mid-pagination leaves you with a half-claimed batch.

Throttling

For a single account on a sensible cadence, throttling won't bite you. The question gets real once you're polling many accounts in parallel: the per-account fair-use limit is one request per endpoint per second, but if you manage 100+ accounts and fire them all at the same moment, you'll feel it on the receiving infrastructure long before any single account does. Stagger the cycles, or batch them across a window.

Errors & retry

Sort responses into three buckets and handle each on its own terms.

Bucket	Examples	What to do
Transient	`network`, `5xx`, `429`	Retry with exponential backoff (1s → 2s → 4s, capped). On `429`, respect `Retry-After` if present.
Permanent	`4xx` (other than 429)	Log and stop the cycle. Usually a config or auth issue — retrying won't help.
Success	`200`	Process the batch — see Where to advance the cursor below.

Where to advance the cursor

Treat the cursor as your commit point: only persist it after downstream finishes the batch. If you save it earlier and downstream then fails, those records are gone for good. Make your handler idempotent on company.id so a retried fetch — which re-delivers the same batch — doesn't double-write.