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 AI 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 phone number, 11 for both, and 0 credits for search. Email and phone 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 $89 per seat a month.

Last updated: September 1, 2026. Every endpoint, limit and price below was checked against the live Cleanlist AI 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 AI's implementation is POST /enrichment/person on API v2, which queries external data providers in sequence until one returns a verified match, then bills for the match. Cleanlist AI owns no contact database of its own, which is the structural reason a miss costs nothing. On Cleanlist AI'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 AI sits in the second group and only partly in the first. Cleanlist AI's API v2 exposes about 30 REST endpoints across search, enrichment, lead lists, skills, sync and exports, but there is no bulk dataset to license, no firehose export and no historical snapshot product, because Cleanlist AI orchestrates providers rather than warehousing records. If your requirement is "give me 40 million company rows in a bucket", Cleanlist AI 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 AI 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 running a multi-provider waterfall on every record viable: the coverage risk sits on Cleanlist AI 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 AI 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 AI's August 7, 2026 index (ZoomInfo, Cognism and Seamless.AI) published no purchasable dollar figure at any tier, while Cleanlist AI publishes its self-serve tiers and the conversion behind them: $49 and $89 per seat a month, and 1 credit per verified email. Seamless.AI alternatives covers what a buyer gets instead when a quote is the only path to a price.

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 AI's August 7, 2026 index. Cleanlist AI Starter is $65.33 per 1,000 on monthly billing ($49 for 750 credits) and $49.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 AI API access?

Minting a clapi_ key requires a Pro plan at $89 per seat a month (1,500 credits per seat), or an AppSumo Tier 5 or higher license. Free ($0, 50 credits a month) and Starter ($49 per seat a month, 750 credits per seat) accounts work in the Cleanlist AI dashboard and Chrome extension but cannot create an API key. Enterprise is custom. Annual billing takes 25% off seat prices, so the practical annual entry price for the API is $67 a month for one Pro seat. Cleanlist AI 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 AI API?

Send the key as a bearer token: Authorization: Bearer clapi_your_key. Cleanlist AI 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 AI 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 AI ships no SDK, so any HTTP client works against the OpenAPI 3.x spec.

What structured filters does the Cleanlist AI 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 AI 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 AI app.

What filters does the company search API accept?

Exactly nine dimensions on Cleanlist AI'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 AI publishes it rather than implying a longer one. Two of those nine carry a casing trap rather than an emptiness problem: funding_stage and the funding round type are accepted by the validator and do return data, but the enum is lowercase with underscores. A probe on September 7, 2026 sent funding_stages with the value series_b and got 10,498 companies back; the same query written as Series B returns zero rows and no error, which is how an invalid enum fails here. 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 AI API not have?

Three gaps are worth knowing before you design a query builder on top of Cleanlist AI. technologies and revenue_ranges are rejected outright by the company search validator, so there is no technographic and no revenue targeting on the Cleanlist AI API. funding_stage works, and the trap is the enum casing rather than the data: series_b returned 10,498 companies on September 7, 2026 while Series B returns zero rows and no error. Cleanlist AI also sells no intent data and has no job-change alerting. If a vendor comparison table shows Cleanlist AI 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 AI API support natural-language search?

No. The Cleanlist AI 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 AI: Clu, the in-app GTM agent, and the Cleanlist AI 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 AI API?

The Cleanlist AI 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 AI'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 AI 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 multi-provider waterfall 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 AI API support webhooks?

The current v2 Cleanlist AI 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 AI's own documentation directs new integrations away from, so any older tutorial showing a Cleanlist AI 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 AI 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 AI 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 AI'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 AI publish an uptime SLA or hold SOC 2?

No, on both counts, as of August 10, 2026. Cleanlist AI 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 AI 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 AI 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 AI 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?

The lead enrichment APIs a buyer is realistically choosing between in 2026 are Cleanlist AI, Apollo, People Data Labs, Clay, Cognism, ZoomInfo and Coresignal. Cleanlist AI's API v2 is the pay-for-results option in that set: 1 credit for a verified email, 10 for a phone number, 11 for both, 0 credits for search, and key minting from the Pro plan at $89 per seat a month. Published prices for the rest, as fetched for Cleanlist AI's August 7, 2026 pricing index, run from Apollo Basic at $49 per seat per month on annual billing, to People Data Labs Pro at $98 a month, to Clay Launch at $167 a month, while ZoomInfo, Cognism and Seamless.AI publish no purchasable figure at any tier. People Data Labs alternatives covers where that dataset fits and where it does not. For ZoomInfo's own endpoints and rate limits, see our ZoomInfo API guide.

Cleanlist AI 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 AI was not among them, and Cleanlist AI 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. Re-checked on August 18, 2026, that same AI Overview cited this Cleanlist AI guide as one of its sources while naming Apollo, ZoomInfo, Hunter, Cognism and Coresignal in the answer text. 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 AI 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 new Cleanlist AI workspace runs 14 days on Pro with 250 credits and three seats, and a free account is $0 with 50 credits a month after that, which is enough to see exactly which fields the waterfall returns before you commit to Pro seats for a key. Related reading: 8 B2B data enrichment APIs compared and the best people search APIs.

See pricing