Lead search and enrichment
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.
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.
Some calls 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 | GET /rest/v2/lead_finder/search_criteria | Retrieve the current criteria catalog for building lead searches |
| Get search criteria values | GET /rest/v2/lead_finder/search_criteria/{criterion_name}/values | Retrieve allowed values for enumerated criteria |
| Search leads | POST /rest/v2/lead_finder/leads | Find people who match your selected criteria |
| Queue lead enrichments | POST /rest/v2/lead_finder/leads/enrichments | Start an asynchronous enrichment batch for selected lead search results |
| List lead enrichments | GET /rest/v2/lead_finder/leads/enrichments | List recent lead enrichment batches and processing statuses |
| Get lead enrichment | GET /rest/v2/lead_finder/leads/enrichments/{uuid} | Retrieve one lead enrichment batch by its returned uuid |