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

# Find emails for search results

> Search for people with Leadsforge API, then find their work emails with an enrichment job.

This guide walks through the most common Leadsforge workflow: find the people who match your ideal customer profile, then get their work emails.

* **Service:** Leadsforge API
* **Base URL:** `https://api.leadsforge.ai/public/v1`
* **Cost:** search and count are free up to a monthly allowance, then each request costs credits, and every cursor page counts as a search request; enrichment charges your email price for each email found. See [Credits](https://developer.salesforge.ai/leadsforge-api/concepts/credits.md).

All examples send your API key in the `Authorization` header and read it from `$LEADSFORGE_API_KEY`.

**1. Size the audience**

Count the people that match your filters before paging through them.

```bash theme={null}
curl -sS https://api.leadsforge.ai/public/v1/search/count \
  -H "Authorization: $LEADSFORGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "leadJobTitles": {"include": ["Head of Sales"]},
    "companyLocations": {"include": ["Germany"]},
    "companyEmployeeNumberRange": {"min": 11, "max": 200}
  }'
```

```json theme={null}
{"totalCount": 1840}
```

If the response has `warnings`, some location values match nothing. Use `GET /filters/locations/suggestions` to find the right spelling. Suggestions are built from people's locations, so they fit `leadLocations`; a suggestion can match no company location in `companyLocations`.

**2. Search**

Send the same filters with a page size. Each lead has an `id`: that is the person ID you enrich later.

```bash theme={null}
curl -sS https://api.leadsforge.ai/public/v1/search \
  -H "Authorization: $LEADSFORGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "limit": 200,
    "leadJobTitles": {"include": ["Head of Sales"]},
    "companyLocations": {"include": ["Germany"]},
    "companyEmployeeNumberRange": {"min": 11, "max": 200}
  }'
```

```json theme={null}
{
  "leads": [
    {
      "id": "6f1e2d3c-4b5a-5968-8776-a5b4c3d2e1f0",
      "firstName": "Jane",
      "lastName": "Smith",
      "jobTitle": "Head of Sales",
      "location": {"city": "Berlin", "state": null, "country": "Germany"},
      "company": {"id": "9b2f6d1e-4c3a-5b8e-a7d6-1f0e9c8b7a65", "domain": "salesforge.ai", "employeeCount": 120}
    }
  ],
  "cursor": "V1StGXR8_Z5jdHi6B-myT3k8LmN0qPwA"
}
```

To get the next page, call `POST /search?cursor=...` with the cursor from the previous page; the body is then ignored. Stop when a page has no cursor or the API answers `410`: once a search has returned 1000 people, the next page answers `410`, so refine your filters to reach the people you need. A cursor stays valid for 20 minutes.

**3. Start an email enrichment job**

Send up to 500 person IDs per job. Add an `Idempotency-Key` so a retried request does not start a second job, and a `clientRequestID` of your own to find the job later in the job list (see [Asynchronous jobs](https://developer.salesforge.ai/leadsforge-api/concepts/async-jobs.md#finding-a-job-again)).

```bash theme={null}
curl -sS https://api.leadsforge.ai/public/v1/enrichment/emails \
  -H "Authorization: $LEADSFORGE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: import-2026-10-21-batch-1" \
  -d '{
    "personIDs": ["6f1e2d3c-4b5a-5968-8776-a5b4c3d2e1f0"],
    "clientRequestID": "import-2026-10-21-batch-1"
  }'
```

The response is `202 Accepted` with the job:

```json theme={null}
{
  "jobID": "0b7d5e7a-3c1f-4f7e-9a2b-8d6c5e4f3a21",
  "channel": "email",
  "status": "in_progress",
  "total": 1,
  "processed": 0,
  "succeeded": 0,
  "failed": 0,
  "reservedCredits": 1,
  "createdAt": "2026-10-21T09:00:00Z",
  "updatedAt": "2026-10-21T09:00:00Z",
  "clientRequestID": "import-2026-10-21-batch-1",
  "statusURL": "/public/v1/enrichment/jobs/0b7d5e7a-3c1f-4f7e-9a2b-8d6c5e4f3a21",
  "resultsURL": "/public/v1/enrichment/jobs/0b7d5e7a-3c1f-4f7e-9a2b-8d6c5e4f3a21/results"
}
```

The job reserves your email price for every person whose email your account did not obtain in the last 30 days. At the end it charges only for emails found.

**4. Wait for the job**

Poll the job until its status is `completed` or `failed`.

```bash theme={null}
curl -sS https://api.leadsforge.ai/public/v1/enrichment/jobs/0b7d5e7a-3c1f-4f7e-9a2b-8d6c5e4f3a21 \
  -H "Authorization: $LEADSFORGE_API_KEY"
```

You can also pass a `webhookURL` when you start the job to receive each person's result as soon as it is ready; the job sends no webhook when it ends, so still poll it for its final status. See [Asynchronous jobs](https://developer.salesforge.ai/leadsforge-api/concepts/async-jobs.md#webhooks).

**5. Read the results**

Page through the results. On `succeeded` results the email is in `payload.email`.

```bash theme={null}
curl -sS "https://api.leadsforge.ai/public/v1/enrichment/jobs/0b7d5e7a-3c1f-4f7e-9a2b-8d6c5e4f3a21/results?limit=500&offset=0" \
  -H "Authorization: $LEADSFORGE_API_KEY"
```

```json theme={null}
{
  "jobID": "0b7d5e7a-3c1f-4f7e-9a2b-8d6c5e4f3a21",
  "results": [
    {
      "jobID": "0b7d5e7a-3c1f-4f7e-9a2b-8d6c5e4f3a21",
      "personID": "6f1e2d3c-4b5a-5968-8776-a5b4c3d2e1f0",
      "channel": "email",
      "status": "succeeded",
      "payload": {"email": "jane@salesforge.ai"},
      "person": {"firstName": "Jane", "lastName": "Smith", "jobTitle": "Head of Sales", "company": "Salesforge"},
      "completedAt": "2026-10-21T10:02:11Z"
    }
  ],
  "offset": 0,
  "limit": 500,
  "total": 1
}
```

A `not_found` result costs nothing. It can be temporary, so you can try those people again later.

## Variations

* **Phone numbers or LinkedIn URLs**: the same flow with `POST /enrichment/phones` (value in `payload.phoneNumber`) or `POST /enrichment/linkedin` (value in `payload.linkedinURL`).
* **People you already know**: instead of `personIDs`, send `people` with a LinkedIn URL, or first name, last name and a company domain or name. Each entry can carry an `externalID` that comes back in its result. For emails and phones, a LinkedIn URL we cannot match comes back `not_found` unless you also send first and last name; LinkedIn enrichment returns `not_found` for anyone we cannot match.
* **One person at a time**: `POST /enrichment/email` and `POST /enrichment/phone` return the value in the same response, without a job.

## Related resources

* [Search and enrichment](https://developer.salesforge.ai/leadsforge-api/concepts/search-and-enrichment.md)
* [Asynchronous jobs](https://developer.salesforge.ai/leadsforge-api/concepts/async-jobs.md)
* [Credits](https://developer.salesforge.ai/leadsforge-api/concepts/credits.md)


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