> ## 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`, `personFilterKeys`, `companyFilterKeys`. Call this before searching: a filter value outside the provider's vocabulary returns zero rows, not an error, and `personFilterKeys`/`companyFilterKeys` map every valid filter key to a one-line meaning so you are not guessing a key name.

## 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 the full list of valid keys. An unknown key is rejected with a 400 naming it, not silently dropped.</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": {"jobTitles": ["CTO"], "countries": ["US"]}, "pageSize": 25}'
```

Returns 429 `lead_finder_search_cap` when the daily search budget is exhausted. Returns 400 with `{"code": "unknown_filter_keys", "unknownKeys": [...], "validKeys": [...]}` when `filters` contains a key that does not exist on the model (e.g. `currentJobTitle` instead of `jobTitles`). An empty filter set (only `countries` set, or nothing set) 400s with a message naming example keys to try.

## Count / search companies

`POST /api/v1/lead-finder/companies/count` (read), `POST /api/v1/lead-finder/companies/search` (read): same shape, company filters (names, domains, industries, types, headquarters, headcount, revenue). Costs the same search budget as people search. Same unknown-key 400 as the people routes.

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


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