Skip to main content
Some Leadsforge operations take longer than one HTTP request can wait: looking up contact details for hundreds of people, collecting the followers of a company page, or finding local businesses in an area. These operations run as jobs. You start a job, get its ID back immediately, and then follow it until it ends.

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 a webhookURL 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 2xx quickly. Any 2xx counts as delivered. Each attempt waits up to 8 seconds for a response.
  • Retries happen on 5xx, 429 and network errors. Other 4xx responses are treated as final and are not retried.
  • Redirects are not followed. A 3xx response counts as a failed delivery.
  • Deduplicate with the X-Webhook-Delivery-Id header. All attempts of one delivery carry the same ID: one ID per person for enrichment, the jobID for followers and maps.
  • The URL must be public. webhookURL must be a public http or https URL with a domain name, not an IP address, or the request fails with 400. Use https: enrichment webhook bodies carry personal data.
An enrichment job does not send a job-level webhook, so poll the job for its final status. By the time a result’s webhook arrives, the result can also be read from the job’s results. Key results by jobID and personID and keep the latest one.

Idempotency keys

Network errors make it unclear whether a start request reached the server. Send an Idempotency-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 gets 429 rate_limited. Only one owner enrichment job can run per maps search; a second one gets 409 conflict. See Rate limits.