Which operations are jobs
Search, lookalike companies and single-person email or phone lookups are not jobs: they answer in the same response.
Job lifecycle
1
Start the job
The start request returns
202 Accepted with the job, including its jobID, a statusURL and a resultsURL. The Location header carries the same path as statusURL.2
Follow the job
Poll the job until its status is final. You can also pass a
webhookURL when you start it to be notified by POST.3
Read the results
Page through the results with
offset and limit.Statuses
Finding a job again
Enrichment, company followers, maps discovery and maps owner jobs each have a list endpoint that returns your jobs, most recent first. Filter it by status, by creation time (from and to, RFC 3339), or by the clientRequestID you sent when you started the job. Set a clientRequestID (up to 128 characters) to your own reference, such as a CRM import ID, so you can recover the job even if you lose its jobID.
Webhooks
Pass awebhookURL when you start a job to be notified by POST. Webhooks are a convenience on top of polling, not a replacement: the job and its results can also be read through the API.
The same rules apply to every webhook:
- Respond with
2xxquickly. Any2xxcounts as delivered. Each attempt waits up to 8 seconds for a response. - Retries happen on
5xx,429and network errors. Other4xxresponses are treated as final and are not retried. - Redirects are not followed. A
3xxresponse counts as a failed delivery. - Deduplicate with the
X-Webhook-Delivery-Idheader. All attempts of one delivery carry the same ID: one ID per person for enrichment, thejobIDfor followers and maps. - The URL must be public.
webhookURLmust be a publichttporhttpsURL with a domain name, not an IP address, or the request fails with400. Usehttps: enrichment webhook bodies carry personal data.
jobID and personID and keep the latest one.
Idempotency keys
Network errors make it unclear whether a start request reached the server. Send anIdempotency-Key header on job start requests and lookalike company search, so a retry does not start or pay for the same work twice.
Use a new key for every distinct request. Retry only after the previous attempt has returned or timed out; do not send the same key from two requests at the same time.
Concurrency
Each account can run a limited number of enrichment, company followers and maps discovery jobs at the same time; a start request beyond that limit gets429 rate_limited. Only one owner enrichment job can run per maps search; a second one gets 409 conflict. See Rate limits.
