> ## Documentation Index
> Fetch the complete documentation index at: https://developer.salesforge.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Asynchronous jobs

> Understand how long-running Leadsforge API operations run as jobs, how to follow them, and how webhooks and idempotency keys work.

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

| Operation | What the job produces |
| - | - |
| Email, phone and LinkedIn enrichment | One result per person, with the value found or the reason none was |
| Company followers search | The people who follow a LinkedIn company page |
| Maps discovery search | Local businesses found in an area |
| Maps owner enrichment | Owners of those businesses, with their email and phone |

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

| Status | Meaning |
| - | - |
| `in_progress` | The job is still running. |
| `completed` | The job finished. A maps owner job can also carry `error` when contact lookups stopped early because credits ran out. |
| `failed` | The job could not finish. Followers and maps jobs carry an `error` field that says why; for an enrichment job, per-person reasons are in its results, and people it had not reached by then have no result. |
| `no_results` | The job finished without results. Used by company followers and maps jobs; a maps owner job also ends this way when none of its businesses got the status `queued` or `cached`. |

### 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.

| Job | When the webhook is sent | Retries |
| - | - | - |
| Enrichment | Once per person, as soon as that person's result is recorded. The body is the result object. | Retried immediately, then redelivered in the background for up to 24 hours. |
| Company followers search | Once, when the job ends. | Retried immediately, then redelivered in the background for up to 24 hours. |
| Maps discovery search and owner enrichment | Once, when the job ends. | Up to 3 attempts close together; no later redelivery. |

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.

| Operation | Behavior of a repeated key |
| - | - |
| Enrichment, company followers and maps jobs | A repeat with the same key in your account (per channel for enrichment) returns the existing job as is, whatever its status and the request body, for as long as that job exists. The body must still be valid, or the repeat gets `400`. |
| Lookalike company search | Keys are remembered for 10 minutes. A repeat returns the original result without charging again; a repeat while the first request still runs returns `409 idempotency_conflict`. |

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](https://developer.salesforge.ai/leadsforge-api/concepts/rate-limits.md).

## Related resources

* [Search and enrichment](https://developer.salesforge.ai/leadsforge-api/concepts/search-and-enrichment.md)
* [Credits](https://developer.salesforge.ai/leadsforge-api/concepts/credits.md)
* [Find emails for search results](https://developer.salesforge.ai/products/leadsforge/find-emails-for-search-results.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.