Lead Enrichment API: A Developer's Guide to Billing, Filters and Limits

A lead enrichment API takes a partial contact record (an email, a LinkedIn URL, or a name plus a company domain) and returns a completed one: verified work email, direct dial, job title and company firmographics. The Cleanlist API v2 at api.cleanlist.ai/api/v2 is one of them, and it prices the work in credits: 1 credit for a verified email, 10 for a direct dial, 11 for both, and 0 credits for search. Enrichment is pay-for-results, so a record the waterfall cannot complete is refunded when the workflow settles. Programmatic access starts on the Pro plan at $229/month.

Last updated: August 10, 2026. Every endpoint, limit and price below was checked against the live Cleanlist API v2 surface on that date.

What is a lead enrichment API?

A lead enrichment API is an HTTP endpoint that accepts a partial record and returns a completed one, so a CRM, a form handler or an agent can fill missing fields at the moment a lead arrives instead of exporting a CSV and re-uploading it later. Cleanlist's implementation is POST /enrichment/person on API v2, which queries 9 external data providers in sequence until one returns a verified match, then bills for the match. Cleanlist owns no contact database of its own, which is the structural reason a miss costs nothing. On Cleanlist's 500-lead enrichment benchmark that waterfall returned a verified email for 98% of leads and a direct dial for 85%.

What is the difference between a lead enrichment API and a B2B data API?

A B2B data API is the wider category: any endpoint serving company or people records, including firmographic lookups, job postings feeds and bulk dataset access. A lead enrichment API is the subset that completes a record you already hold. Cleanlist sits in the second group and only partly in the first. Cleanlist's API v2 exposes about 30 REST endpoints across search, enrichment, lead lists, smart agents, sync and exports, but there is no bulk dataset to license, no firehose export and no historical snapshot product, because Cleanlist orchestrates providers rather than warehousing records. If your requirement is "give me 40 million company rows in a bucket", Cleanlist is the wrong shape. If it is "complete these 4,000 rows and push them to HubSpot", it is the right one.

How does pay-for-results billing differ from per-call billing?

Per-call billing charges you for the lookup. Pay-for-results billing charges you for the answer. Cleanlist reserves credits when an enrichment workflow is dispatched and refunds the unused portion when it settles, so a record the waterfall cannot fill is returned with credits_charged: 0. The practical rule for an integration is to read credits_charged from the settled workflow rather than assuming the estimate was the bill. This is also what makes querying up to 15+ providers per record viable: the coverage risk sits on Cleanlist rather than on your balance. A 1,000-row full-contact job reserves 11,000 credits and charges only for rows that returned data.

What pricing models do enrichment APIs use?

Five shapes, and the shape matters more than the headline number. Cleanlist fetched 21 vendor pricing pages on August 7, 2026 for its B2B contact data pricing index, and every published model reduced to one of these:

A sixth shape is "no published price at all". Three of the 16 contact data vendors in Cleanlist's August 7, 2026 index (ZoomInfo, Cognism and Seamless.AI) published no purchasable dollar figure at any tier, while Cleanlist publishes every tier and the conversion behind it: $79, $229 and $599 a month, 1 credit per verified email.

What does an enrichment API cost per 1,000 verified emails?

Normalized to cost per 1,000 verified emails, the eight vendors that publish enough information to compute it ranged from $19.60 to $582.35 in Cleanlist's August 7, 2026 index. Cleanlist Starter is $52.67 per 1,000 on monthly billing ($79 for 1,500 credits) and $39.33 on annual billing, which puts it mid-table rather than cheapest. Apollo Basic on annual billing computes to $19.60 at its published 1-credit reveal rate, People Data Labs Pro monthly to $280.00, and UpLead Essentials monthly to $582.35. Only 8 of 16 vendors published enough to run that division at all. Of the other eight, three publish no purchasable price at any tier and the rest publish a price and a credit allowance while withholding the credits-per-email conversion.

Which plans include Cleanlist API access?

Minting a clapi_ key requires a Pro plan at $229/month for 5,000 credits, or an AppSumo Tier 5 or higher license. Free ($0, 30 credits a month, no card) and Starter ($79/month, 1,500 credits) accounts work in the Cleanlist dashboard and Chrome extension but cannot create an API key. Scale is $599/month for 15,000 credits. Annual billing takes 25% off any paid tier, so the practical annual entry price for the API is $171.75/month. Cleanlist does not offer sub-accounts, white-label keys or programmatic key provisioning, which rules out the "one key per end customer" reseller pattern. Current rates are on the pricing page.

How do I authenticate with the Cleanlist API?

Send the key as a bearer token: Authorization: Bearer clapi_your_key. Cleanlist issues clapi_ keys from the dashboard with no approval queue and no sales call, and a Clerk session JWT also works when calling from an authenticated app session. Beyond the token, every endpoint checks one of 14 granular OAuth scopes. Cleanlist grants those scopes per user rather than per key, so there is no read-only key mode and a key can do whatever the person who minted it can do. Call GET /whoami before wiring a key into a job: it returns the identity, scopes, plan tier and organization the key resolves to. Keys rotate or revoke from the dashboard and revocation takes effect immediately. Cleanlist ships no SDK, so any HTTP client works against the OpenAPI 3.x spec.

What structured filters does the Cleanlist people search API accept?

POST /search/people accepts 20+ structured filter dimensions, including job title, seniority, location, company headcount band, industry, skills, education and past roles. Job function and department are not filters on the Cleanlist API, so job title is the proxy for both. Search costs 0 credits, which means you can iterate on a query until the cohort is right and only spend when you save or enrich the results. GET /search/people/filters returns the live allowlist and the accepted enum values, so a client can validate a filter set at build time instead of guessing from documentation. The same filter surface powers People Search inside the Cleanlist app.

What filters does the company search API accept?

Exactly nine dimensions on Cleanlist's POST /search/companies: company name, domain, industry, headcount band, HQ location, company type, funding stage, last funding round type and year founded. That is the whole list, and Cleanlist publishes it rather than implying a longer one. Company search also costs 0 credits. There is a related endpoint, POST /search/companies/similar, for lookalike expansion from a seed company. Company enrichment through POST /enrichment/company is synchronous and costs 1 credit, returning name, domain, HQ location and LinkedIn URL. Industry and employee count are documented response fields but come back empty on most records today, so do not build downstream logic on them.

Which filters does the Cleanlist API not have?

Three gaps are worth knowing before you design a query builder on top of Cleanlist. technologies and revenue_ranges are rejected outright by the company search validator, so there is no technographic and no revenue targeting on the Cleanlist API. funding_stage is accepted by the schema but the underlying column is empty, so it silently returns zero results and is not a usable filter today. Cleanlist also sells no intent data and has no job-change alerting. If a vendor comparison table shows Cleanlist with technographic or intent columns ticked, that table is wrong. Building an ICP on firmographics plus title plus headcount is the pattern that works here.

Does the Cleanlist API support natural-language search?

No. The Cleanlist REST API has no natural-language endpoint. POST /search/people and POST /search/companies take structured JSON filters, and there is no route that accepts a sentence like "VPs of Engineering at 50 to 200 person software companies in the US". Natural language is real in two other places at Cleanlist: the in-app Copilot, and the Cleanlist MCP server at mcp.cleanlist.ai, where the model you are already talking to translates prose into structured filters and calls the same tools. If you want prose in and leads out from your own code, have your own LLM emit filter JSON and post that. GET /search/people/filters exists so that JSON can be validated against the live allowlist first.

What are the rate limits on the Cleanlist API?

The Cleanlist API allows 60 requests per minute per organization and 30 requests per minute per API key. AppSumo lifetime licenses without a paid plan are held to 30 per minute per organization. Agent workloads usually hit a different limit first: Cleanlist's People Search carries a separate hard cap of 60 searches per API key per UTC day. Exceeding any limit returns HTTP 429 with a Retry-After header and a rate_limited error body, so a client can back off on a published signal rather than a guess. Cleanlist publishes these numbers on its API page instead of gating them behind a sales conversation, and they were current on August 10, 2026.

How do I estimate the cost of a bulk job before I run it?

Call POST /credits/estimate before spending. It returns the credit cost of the job, the organization's current balance, and whether that balance is sufficient, as a signed quote carrying a five-minute TTL. POST /enrichment/bulk then runs the job with that quote attached, which is the mechanism that stops an automated run from overspending a balance. This matters most when an agent holds the key: the spend ceiling is fixed before the model decides anything. In credits, a 1,000-lead email-only job quotes at 1,000 and a full-contact job (email and phone) quotes at 11,000. The settled workflow reports what you actually paid.

How do I enrich 1,000 leads through the API?

Four calls. POST /lead-lists creates the list. POST /lead-lists/{id}/leads adds records at 0.5 credits per newly saved lead, or POST /lead-lists/{id}/csv-import loads a file. POST /credits/estimate quotes the job. POST /enrichment/bulk dispatches it and returns a workflow_id immediately rather than blocking, because a waterfall across 15+ providers takes longer than a request timeout allows. Modes are partial (email plus LinkedIn, title and company) at 1 credit, phone_only at 10, and full at 11. When the job settles, POST /sync/crm pushes the finished rows to HubSpot, Salesforce or Outreach at 0.2 credits per lead.

import os, time, requests
 
BASE = "https://api.cleanlist.ai/api/v2"
H = {"Authorization": f"Bearer {os.environ['CLEANLIST_API_KEY']}"}
LIST_ID = "your_lead_list_id"
 
quote = requests.post(f"{BASE}/credits/estimate", headers=H,
                      json={"lead_list_id": LIST_ID, "mode": "full"}).json()
if not quote["sufficient"]:
    raise SystemExit("Not enough credits")
 
run = requests.post(f"{BASE}/enrichment/bulk", headers=H,
                    json={"lead_list_id": LIST_ID, "mode": "full"}).json()
 
while True:  # there are no v2 webhooks
    s = requests.get(f"{BASE}/enrichment/status/{run['workflow_id']}", headers=H).json()
    if s["status"] in ("completed", "failed"):
        break
    time.sleep(5)
 
print(s["credits_charged"])  # what you actually paid, after refunds

Does the Cleanlist API support webhooks?

The current v2 Cleanlist API is poll-based. There is no endpoint to register a callback URL on v2 and no signed-payload delivery. Asynchronous operations (person enrichment, bulk list enrichment, smart-agent runs) return a workflow_id, and you poll GET /enrichment/status/{workflow_id} or GET /smart-agents/{id} until the status is terminal. Webhook delivery exists only on the frozen legacy v1 API, which Cleanlist's own documentation directs new integrations away from, so any older tutorial showing a Cleanlist webhook is describing v1. If you need push semantics today, a polling worker with exponential backoff is the whole integration, and it is sufficient at the job sizes this API is built for.

Is there a standalone email verification endpoint?

No. Verification runs inside enrichment on the Cleanlist API. Every email the waterfall returns is checked for syntax, MX and DNS records, and SMTP deliverability before it is billed, which is what the 1-credit email price buys. What Cleanlist does not offer is a /verify route you can point at a list you already own to score addresses sourced elsewhere. If that is the job, a dedicated validation API is the better fit, and the economics are different: in Cleanlist's August 7, 2026 index, every verification vendor surveyed published a public per-unit price, while only half the contact data vendors did. More on the mechanics in waterfall enrichment.

Does Cleanlist publish an uptime SLA or hold SOC 2?

No, on both counts, as of August 10, 2026. Cleanlist does not publish a contractual uptime commitment and is not SOC 2 certified. The API is served over HTTPS with scoped bearer tokens that can be revoked instantly, every endpoint is checked against one of 14 OAuth scopes, and the rate limits above are published openly, but none of that is an availability guarantee. If your procurement process requires an SLA or an audit report, raise it before you write the integration rather than after. Cleanlist states this on the API page rather than leaving it to a discovery call.

Can an AI agent call the enrichment API directly?

Yes, and the envelope is built for it. Every Cleanlist API response carries task_id, timestamp_ms, credits_charged, a usage string suggesting the next call, and agent_instructions for LLM callers, so a model has a machine-readable hint rather than having to infer the next step. The guardrail that makes handing an agent a key reasonable is the signed quote from POST /credits/estimate, plus the fact that search costs 0 credits, so an exploring agent burns rate limit and not balance. If you work inside Claude rather than writing HTTP calls, the Cleanlist MCP server exposes the same search, enrichment and lead-list tools over OAuth, and it is in beta.

Which lead enrichment APIs do AI answer engines cite today?

Cleanlist pulled the live Google SERP for "lead enrichment api" on August 10, 2026 as part of its own AI visibility tracking. The AI Overview served on that query cited eleven domains: hunter.io, cognism.com, generect.com, pipeline.zoominfo.com, cufinder.io, trestleiq.com, peopledatalabs.com, apify.com, autobound.ai, clay.com and scrap.io. Cleanlist was not among them, and Cleanlist ranked 16 on the adjacent query "b2b data api" with an AI Overview present and no citation. Worth knowing if you are choosing an API from an AI answer: nine of the twelve cited pages were blog explainers or listicles and only three were vendor API product pages (Hunter, People Data Labs and an Apify listing), so the set reflects who publishes an explainer as much as who ships an API. Verify billing shape against the vendor's own docs.

What should you test before integrating a lead enrichment API?

Run 200 of your own rows, not the vendor's sample. Measure three things: fill rate per field, deliverability on the emails returned (send to them and count bounces rather than trusting a match rate), and what you were actually charged versus quoted. On Cleanlist that last check is one field, credits_charged on the settled workflow, and it should come in below an 11-credit-per-row reservation on any real list. A free Cleanlist account is $0 with 30 credits a month and no card, which is enough to see exactly which fields the waterfall returns before you commit to $229/month for a key. Related reading: 8 B2B data enrichment APIs compared and the best people search APIs.