> ## Documentation Index
> Fetch the complete documentation index at: https://www.foxreach.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Lead Finder

> Search a licensed people/company database and reveal verified work emails. Feature-flagged, off by default.

All routes 404 while Lead Finder is disabled for the workspace (same as the dashboard). Credit purchase (Stripe checkout) and the provider webhook are browser/server-only and not exposed here.

## Get filter vocabularies

`GET /api/v1/lead-finder/filter-options` (read)

Returns `industries`, `companyTypes`, `headcountGrowthTimespans`, `allowedCountries`, `blockedCountries`, `coverage`. Call this before searching: a filter value outside the provider's vocabulary returns zero rows, not an error.

## Count / search people

`POST /api/v1/lead-finder/count` (read): free, does not spend search budget.
`POST /api/v1/lead-finder/search` (read): consumes one page of the workspace's daily search budget.

<ParamField body="filters" type="object" required>Person filters: job title, location, industry, company, headcount, and more. See filter-options for valid values.</ParamField>
<ParamField body="pageSize" type="integer" default="25">1-50.</ParamField>
<ParamField body="pageToken" type="string">From a previous page's `nextPageToken`.</ParamField>

```bash theme={null}
curl -X POST https://api.foxreach.io/api/v1/lead-finder/search \
  -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"filters": {"currentJobTitle": ["CTO"], "countries": ["US"]}, "pageSize": 25}'
```

Returns 429 `lead_finder_search_cap` when the daily search budget is exhausted.

## Count / search companies

`POST /api/v1/lead-finder/companies/count` (read), `POST /api/v1/lead-finder/companies/search` (read): same shape, company filters (name, domain, industry, type, headquarters, headcount, revenue). Costs the same search budget as people search.

## Reveal emails

`POST /api/v1/lead-finder/reveal` (write): spends paid reveal credits, one per newly-charged person.

<ParamField body="people" type="array" required>Up to 100 person objects from a search result, each with at least `id`.</ParamField>

Returns `batchId`, `requested`, `charged`, `reused`, `inProgress`, `unsearchable`, `balance`. Reused/unsearchable people cost nothing.

## Reveal history and status

`GET /api/v1/lead-finder/reveals` (read): the workspace's reveal history for one month (`?month=YYYY-MM&status=&q=&page=&pageSize=`), newest first, with totals.
`GET /api/v1/lead-finder/reveals/{batchId}` (read): poll a specific batch's pending/found/not-found counts.

## Credit balance

`GET /api/v1/lead-finder/credits` (read): balance, monthly allowance, coverage, and today's search budget usage.