# Lead search and enrichment

> **Documentation index**
> Browse the [Woodpecker developer documentation index](https://developers.woodpecker.co/llms.txt) to discover related API references, guides, webhooks, MCP tools, and CLI documentation.

> :::warning Upcoming API changes
The Lead Finder search endpoints will change in the near future. Review the [summary of upcoming changes](/docs/lead-finder/lead-search-and-enrichment/upcoming-api-changes) to prepare your integration.
:::

:::warning Upcoming API changes
The Lead Finder search endpoints will change in the near future. Review the [summary of upcoming changes](/docs/lead-finder/lead-search-and-enrichment/upcoming-api-changes) to prepare your integration.
:::

Use this flow when you want to find leads who match a target audience and are not already coming from your Woodpecker prospects database.

**Start by reading the Lead Finder criteria catalog**, then fetch current values for filters such as country, industry, or job title role. **Use those criteria to search for leads**. The search response returns compact lead records, including the `uid` needed for enrichment.

Search criteria and allowed values can change over time, so build search requests from the current criteria endpoints. Lead profile fields also depend on data availability: when a profile value is not available, scalar fields can be returned as `null`, and array fields can be returned as an empty array.

When you know which leads you want to work with, **queue them for enrichment**. Enrichment runs asynchronously: the queue response gives you a batch `uuid`, and you use the list or get endpoints to check when processing is complete. Enriched leads can be added to the global prospect list or selected campaigns with `target_campaign_ids`.

:::info Credit usage
Some requests in this flow use account credits. Searching for leads and viewing returned lead data costs 1 credit per lead. For enrichment requests, credits are applied only when enrichment finds data: 1.5 credits for enriching a lead and finding an email. GET endpoints used to read criteria or check enrichment status do not use credits.
:::

## Available endpoints

| Endpoint | Method and path | Use it to |
|----------|-----------------|-----------|
| [Get search criteria](https://developers.woodpecker.co/docs/lead-finder/lead-search-and-enrichment/get-search-criteria.md) | `GET /rest/v2/lead_finder/search_criteria` | Retrieve the current criteria catalog for building lead searches |
| [Get search criteria values](https://developers.woodpecker.co/docs/lead-finder/lead-search-and-enrichment/get-search-criteria-values.md) | `GET /rest/v2/lead_finder/search_criteria/{criterion_name}/values` | Retrieve allowed values for enumerated criteria |
| [Search leads](https://developers.woodpecker.co/docs/lead-finder/lead-search-and-enrichment/post-search-leads.md) | `POST /rest/v2/lead_finder/leads` | Find people who match your selected criteria |
| [Queue lead enrichments](https://developers.woodpecker.co/docs/lead-finder/lead-search-and-enrichment/queue-lead-enrichments.md) | `POST /rest/v2/lead_finder/leads/enrichments` | Start an asynchronous enrichment batch for selected lead search results |
| [List lead enrichments](https://developers.woodpecker.co/docs/lead-finder/lead-search-and-enrichment/list-lead-enrichments.md) | `GET /rest/v2/lead_finder/leads/enrichments` | List recent lead enrichment batches and processing statuses |
| [Get lead enrichment](https://developers.woodpecker.co/docs/lead-finder/lead-search-and-enrichment/get-lead-enrichment.md) | `GET /rest/v2/lead_finder/leads/enrichments/{uuid}` | Retrieve one lead enrichment batch by its returned `uuid` |