Lead Enrichment

Search and enrich leads by company, industry, job title, location, and more.

POST /lead_enrichment_list

Lead enrichment costs 1 credit per valid or accept-all email returned.

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.

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.

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.

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.

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

Input

{
  "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"]
}

Output

{
  "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
}

Error

{
  "status": "error",
  "error": {
    "code": "validation_error",
    "message": "listname: Field required"
  },
  "success": false
}

Retrieving results

• Check List Status

• Download List Data