> For the complete documentation index, see [llms.txt](https://developer.parvenu.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.parvenu.io/search/lead-enrichment.md). # Lead Enrichment Search and enrich leads by company, industry, job title, location, and more. `POST` `/lead_enrichment_list` {% hint style="info" %} Lead enrichment costs **1 credit** per valid or accept-all email returned. {% endhint %} Search for and enrich leads using filters like company domain, industry, job title, location, and company size. Returns enriched contact data with validated email addresses. {% hint style="info" %} This is a bulk enrichment endpoint. The process has three steps: (1) start enrichment here, (2) check status with `/check_list_status`, (3) download results with `/download_list`. {% endhint %} **Headers** | Name | Value | | ------------ | ------------------ | | Content-Type | `application/json` | **Body** | Name | Type | Description | | ----------------------- | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `api_key` | string | Your API Key. | | `listname` | string | The list to create or update with enriched leads. | | `fetch_count` | integer | Number of leads to fetch. Minimum 1. | | `unique` | boolean | Optional, default `true`. Skips people who were recently added to your account; they are not charged. People added longer ago are fetched again. Set `false` to fetch everyone again. See **Duplicates** below. | | `email_enrichment` | boolean | Optional. When true (default), leads are email-enriched and verified, billed at 1 credit per valid business email. When false, the email step is skipped and billing drops to 0.2 credits per record. | | `company_domain` | array\[string] | Optional. Filter by company domains, e.g. `["acme.com"]`. | | `company_industry` | array\[string] | Optional. Include these industries (strict enum, see Industries). | | `company_keywords` | array\[string] | Optional. Free-text company keywords, e.g. `["roofing","solar"]`. | | `contact_job_title` | array\[string] | Optional. Job titles to include, e.g. `["CEO","Owner"]`. | | `contact_location` | array\[string] | Optional. Location filter (see Search Lead Locations). | | `contact_city` | array\[string] | Optional. Free-text city filter. | | `size` | array\[string] | Optional. Company size buckets (strict enum): `1-10`, `11-50`, `51-200`, `201-500`, `501-1000`, `1001-5000`, `5001-10000`, `10001+`. | | `company_not_industry` | array\[string] | Optional. Industries to exclude. | | `company_not_keywords` | array\[string] | Optional. Company keywords to exclude. | | `contact_not_job_title` | array\[string] | Optional. Job titles to exclude. | | `contact_not_location` | array\[string] | Optional. Locations to exclude. | {% hint style="info" %} Location format: use `"state, country_code"` (e.g. `"california, us"`) or a full country name (e.g. `"united states"`). State names must be spelled out in full, abbreviations like `"CA"` will not work. Input is case-insensitive and normalized to lowercase. {% endhint %} **Duplicates** A person is never added to the same list twice, whatever `unique` is set to. | The person is... | With `unique: true` (default) | With `unique: false` | | ---------------------------------------- | ----------------------------------- | ----------------------------------- | | Already on this list, added recently | Skipped, not charged | Blank fields filled in, not charged | | Already on this list, added earlier | Blank fields filled in, not charged | Blank fields filled in, not charged | | Only on your other lists, added recently | Skipped, not charged | Added to this list and charged | | Only on your other lists, added earlier | Added to this list and charged | Added to this list and charged | | Not in your account | Added and charged | Added and charged | When a person already on the list is refreshed, only empty fields are filled in. Existing data, including a verified email, is never replaced. Their history shows a 0-credit `Already in list` line. If everyone the search finds is already in your account, the job still finishes as `done`, with `status_detail: "only contacts already in your lists"` on `/check_list_status`. Nothing new is added and the credits are refunded. This is not an error; change your filters to find new people. **Response** This endpoint starts a background job and answers with an acknowledgement, not the leads. See Response Format for the fields every endpoint returns. | Field | Description | | ----------- | ---------------------------------------------------------------------------------- | | `status` | Job state: `queued`, `processing`, `done`, `not_found`, `cancelled` or `error`. | | `job_id` | The job handle, as a string. | | `list_name` | The list the results are being written to. | | `message` | A short note about the job. | | `view` | Which part of the list the job covers. `all` unless you asked for a narrower view. | | `truncated` | `true` when the job was cut down to fit a limit. | Poll `/check_list_status` until the list reports `done`, then download the rows. **Example** {% tabs %} {% tab title="Input" %} ```json { "api_key": "your_api_key", "listname": "Roofing Owners in California", "fetch_count": 50, "company_industry": ["construction"], "company_keywords": ["roofing"], "contact_job_title": ["CEO", "Owner", "Founder"], "contact_location": ["california, us"], "size": ["1-10", "11-50", "51-200"] } ``` {% endtab %} {% tab title="Output" %} ```json { "status": "queued", "job_id": "918273", "list_name": "Roofing Owners in California", "message": "Processing search enrichment for Roofing Owners in California. Check the list status for updates.", "view": "all", "truncated": false, "credits_used": 0, "credits_remaining": 4823, "success": true } ``` {% endtab %} {% tab title="Error" %} ```json { "status": "error", "error": { "code": "validation_error", "message": "listname: Field required" }, "success": false } ``` {% endtab %} {% endtabs %} **Retrieving results** * Check List Status * Download List Data