What is API Enrichment?
API enrichment is the practice of enriching records programmatically by sending them to one or more data providers over an HTTP API and receiving the completed, verified fields back in the response or from a polled workflow.
API Enrichment, explained
API enrichment is the practice of completing records programmatically instead of by uploading spreadsheets. Your application POSTs an identifier (an email, a company domain, a LinkedIn URL, or a name plus company) to a data enrichment API, the provider matches it and returns the missing fields, and your code writes them straight into the CRM, the warehouse, or the product. The record is complete before a human ever opens it.
A data enrichment API is what turns enrichment from a batch chore into a step in a pipeline. Records get completed at the moment they arrive: a form fill, a webhook from a marketing tool, a signup, a row in a sync job. This page defines the practice. If you are here to build against ours, the endpoint list, the credit price of every route and the published rate limits are on the Cleanlist AI data enrichment API page, and a market overview of the alternatives is in best B2B data enrichment APIs.
How does a data enrichment API work?
Five steps, and step three is where API enrichment differs from a spreadsheet upload.
- ●Authenticate: every request carries a bearer token in an Authorization header. The exact key format and where to generate one are on the Cleanlist AI API page.
- ●Dispatch: you POST the identifier you hold. Company enrichment answers synchronously; person and bulk enrichment answer immediately with a workflow id because the waterfall runs across providers behind the scenes.
- ●Poll: for asynchronous work you call the status endpoint with the workflow id until it reaches a terminal status. Cleanlist AI publishes no latency figure, so the correct client design is exponential backoff rather than a fixed interval.
- ●Receive: the response carries the enriched fields, a task id, a timestamp, and the credits actually charged.
- ●Reconcile: you write the fields back, record what you paid, and decide what to do with the rows that returned nothing.
The request and response shapes for each route, including which fields reliably come back and which arrive null, are documented on every Cleanlist AI v2 endpoint and what it costs.
What does a data enrichment API cost?
- ●Per result, not per call: Cleanlist AI charges 1 credit for a verified email, 10 for a phone number, 11 for both, and 1 for a company record. A lookup that returns nothing charges nothing, and search costs 0 credits.
- ●Quote before large jobs: the credits estimate endpoint returns the cost, your balance, and whether it is sufficient, so a bulk dispatch never fails halfway on funds.
- ●Plan gating: API keys come with the Pro plan at $89 per seat a month with 1,500 credits per seat, and with Enterprise. They do not work during the 14-day Pro trial: a key used in the trial returns `403`. The MCP server, which gives AI agents the same enrichment tools, is included from Starter and in the trial. See pricing.
How does a data enrichment API compare with Apollo's API?
The two models differ in where the data comes from and what search returns. Apollo's REST API searches Apollo's own records for free but returns no emails or phone numbers from search; each contact detail costs credits through enrichment (1 for an email or demographic data, 8 more for a mobile number), bulk calls take 10 people, and phone numbers arrive by webhook or polling. A waterfall enrichment API like Cleanlist AI's routes each record across 25+ providers and charges only when a verified result comes back. The full breakdown, with Apollo's rate limits by plan, is in our Apollo API guide.
How do you handle enrichment API rate limits and retries?
Every enrichment API imposes a per-key and a per-organization ceiling, and the design that survives contact with one is the same everywhere: size the dispatch loop under the lower of the two limits, widen the delay on each poll miss rather than polling on a fixed interval, and stop on a terminal status. Treat an empty result as a valid answer rather than an error worth retrying, because a retry that returns data on the second attempt is billed like any other result. Cache what you have already resolved and keep your own ledger of enriched ids. Cleanlist AI publishes its exact ceilings, its polling contract, and the honest list of what the v2 API does not do on the Cleanlist AI enrichment API reference, which is the page to build against.
What data can a data enrichment API return?
A data enrichment API returns the identity and contact fields a record was missing. Through Cleanlist AI that is a verified work email, a phone number, a LinkedIn URL, job title, seniority and department on the person side, and name, domain, HQ location and LinkedIn URL on the company side. Every email is checked for syntax, DNS and MX, and an SMTP handshake before it is returned, and catch-all, disposable and role-based domains are flagged rather than silently passed through. What it does not return is worth knowing before you design a schema: there is no revenue-range field, no technographic or tech-stack field and no intent signal on the Cleanlist AI API, and a few response keys arrive present and null rather than as an error.
What is the difference between an enrichment API and a contact database API?
A contact database API licenses records out of one vendor's own store, so you pay per lookup whether or not the record is the one you needed, and coverage is capped by that single database. An enrichment API orchestrates: it takes your identifier, routes it across many sources, and returns the assembled record. Cleanlist AI owns no contact database, which puts the coverage risk on the platform rather than on your balance, because a miss is not billed. The trade runs the other way too. There is no bulk dataset to license, no firehose export and no historical snapshot, so a team that wants to hold the data rather than query it is buying the wrong category.
API enrichment vs batch enrichment
- ●API enrichment: one record at a time, at the moment it arrives, driven by your code. Right for inbound lead flow, signup completion, and in-product data.
- ●Batch enrichment: a whole list at once on a schedule. Right for quarterly CRM passes and list preparation. The bulk endpoint covers this without leaving the API.
- ●[Waterfall enrichment](/glossary/waterfall-enrichment): the architecture underneath both. A single Cleanlist AI call routes the record across 25+ providers and normalizes every response into one schema, so you integrate once rather than per vendor.
The reason to buy the cascade rather than build it is maintenance, not concept. Every provider ships its own auth scheme, rate limits, field names, and response format, and each of those changes on the vendor's schedule. On the Cleanlist AI 500-Lead Enrichment Benchmark, 2026, that cascade returned a verified email for 98% of 500 stratified B2B leads and a phone number for 85%, against 70-80% and 30-60% from single-source databases on the identical leads.
Related operations: data appending is the same fill-the-blanks job run on a file, email append is the narrow case where only the address is missing, and list building is what produces the records you enrich. For agent-driven workflows the same tools are exposed on the MCP server, and object-level schemas live at enrich contacts and enrich companies.
Expert definition
“The hard part of a data enrichment API is never the first call. It is the second year, when six providers have each changed an auth scheme, a rate limit, and a field name on their own schedule, and your normalization layer is the thing that breaks. That maintenance is what teams are actually buying when they put one endpoint in front of the cascade. Judge an enrichment API on three things: does it bill you when it misses, does it tell you which source produced each field, and does it give you a workflow you can poll instead of a connection you have to hold open.”
References & Sources
- [1]
- [2]
What is a data enrichment API?
A data enrichment API is an HTTP endpoint that completes a partial record programmatically. Your application POSTs an identifier such as an email, a company domain, a LinkedIn URL, or a name plus company, and the service matches it against data sources and returns the missing fields in the response or from a polled workflow. It removes the CSV round trip so records are complete at the moment they enter your system.
Is enrichment through an API synchronous or asynchronous?
It depends on how much work sits behind the call. Company enrichment resolves against one record and can answer inline, so it is normally synchronous. Person enrichment runs a waterfall across multiple providers, which takes longer than a request should be held open for, so it is normally asynchronous: the dispatch returns a workflow identifier immediately and your client polls a status route until it reaches a terminal state. Bulk enrichment is always asynchronous for the same reason. Cleanlist AI follows exactly this split, and the endpoint names, request bodies and polling contract are documented on the Cleanlist AI API page at /product/api.
How do I handle enrichment API failures and rate limits?
Use exponential backoff on polling, widening the delay on each miss, capping it, and stopping on a terminal status, rather than a fixed interval tuned to a latency figure nobody published. Size the dispatch loop under the lower of the per-key and per-organization ceilings. Cache resolved records so you do not pay twice, and treat an empty result as a valid answer rather than an error worth retrying. Cleanlist AI publishes its exact ceilings and its polling contract on the Cleanlist AI API page at /product/api.
How much does API enrichment cost per record?
Cleanlist AI bills per result rather than per call: 1 credit for a verified email, 10 for a phone number, 11 for both, and nothing when a lookup returns no data. API access starts on the Pro plan at $89 per seat a month with 1,500 credits per seat. Quote large jobs with the credits estimate endpoint first, which returns the cost, your balance, and whether it is sufficient.
Are retried enrichment calls billed twice?
Yes, if the retry returns data, because billing follows results rather than requests. A re-dispatch of the same record is a new billable job rather than a replay of the first one, so the safe pattern is to store the identifier the dispatch returned and poll that, instead of sending the record again. Keeping your own ledger of which ids you have already enriched is what stops a retry loop from quietly spending twice. The current behaviour of the Cleanlist AI enrichment routes is documented on the Cleanlist AI API page at /product/api.
One endpoint, 25+ providers behind it
POST an email, a domain, or a LinkedIn URL to the Cleanlist AI v2 API and get a verified, normalized record back. A missed email or phone number costs nothing. API keys come with Pro at $89 per seat a month; during the 14-day Pro trial, run the same enrichment in the app or through the MCP server.
A demo of Clu, the Cleanlist AI agent, doing this for a whole list. Asked: Find the verified work email for everyone in Series B sales leaders Clu runs the tools, asks for confirmation before spending credits (Find work emails for 212 leads on Series B sales leaders, 212 credits), fills the list row by row and reports: 197 verified emails on the list, 15 not found. Want phone numbers for the 197 next?
Describe the job once. An agent runs it every week.
Clu turns one sentence into an agent. It searches 1B+ profiles, finds verified emails and phone numbers across 25+ providers, adds the people to your sequence and posts each run to Slack.
Weekly ICP outbound
Built by Clu from: “Every week, find 500 new people who match my ICP, get their emails and phones, and add them to Series B outbound.”
- Searched 1B+ profiles for new ICP matches500 foundPeople Search
- Ran the waterfall across 25+ providers487 emails · 412 phonesWaterfall
- Verified every email and phoneSMTP + catch-allVerification
- Added them to Series B outbound500 peopleSequences
- Posted the run to #pipelineSlackAgents
Friday 4:52 PM15 replies · 5 calls booked
Everything in the 14-day Pro trial
- Clu and agentsDescribe the job in one sentence. Clu builds the agent, runs it on a schedule or a CRM trigger and posts every run to Slack.
- People and Company SearchFind your buyers in 1B+ profiles from one sentence. Searching costs 0 credits.
- Waterfall enrichmentAsk 25+ providers in order and stop at the first verified email or phone number. 98% verified work emails and 85% phone numbers on a 500-lead benchmark.
- Email verificationRun SMTP and catch-all checks on every address before it reaches a sequence, at half a credit an email.
- ICP scoringScore every lead 0 to 100 against your ICP, with the reasons written down. The Research and Qualification skills do the digging.
- SequencesSend email from your reps' own inboxes, with call tasks. A reply stops the sequence. Sending costs 0 credits.
- CRM syncTwo-way sync with HubSpot, Salesforce and Pipedrive. Push finished lists to Outreach, Salesloft and Lemlist.
- Chrome extensionGet a verified email and phone number in one click on LinkedIn, Sales Navigator, Salesforce and HubSpot.
- MCP and APIRun the same search and waterfall from Claude or ChatGPT with 36 MCP tools, or from your own code with the REST API.
14 days of Pro, free: 250 credits, 3 seats, agents, Sequences and Clu in Slack. Then Free at 50 credits a month, or Starter at $49 and Pro at $89 a seat a month.
Where to next
Related terms
- Data EnrichmentData enrichment is the process of adding information from external sources to the data records you already have, so sales and marketing teams work from records that are more complete and more accurate.
- Waterfall EnrichmentWaterfall enrichment is a way to fill missing contact data by asking several data providers in turn: each record goes to the next provider only when the one before it returns no verified result, and the cascade stops at the first verified email or phone number.
- Data AppendingData appending is the process of filling empty fields on records you already have by matching them against external data sources, adding what is missing without overwriting the values already in the record.
- Email AppendEmail append is the process of recovering the missing email address on a contact record you already hold, by matching the record's name and company against external data sources and returning a verified work email.
- List BuildingList building is the process of assembling a targeted database of B2B prospects: defining the ideal customer profile, sourcing matching companies and contacts, then enriching and verifying every record before outreach starts.
- Contact EnrichmentContact enrichment is the process of adding professional data points such as job title, phone number, LinkedIn profile and employer to individual contact records, using external data sources.
- Reverse ETLReverse ETL is the process of syncing data from a central data warehouse or data lake back into operational tools like CRMs, marketing platforms, and sales engagement systems where teams can act on it.
Compare the tools
Tell Clu who you sell to.
Clu finds the buyers, verifies every email and phone number across 25+ providers, and scores each lead against your ICP.
14 days of Pro, free.