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.
- 6 sections
- 5 questions answered
- 2 cited sources
Key takeaways
Completes records in code at the moment they arrive, instead of in a CSV round trip
Company enrichment is synchronous; person and bulk enrichment return a workflow_id you poll
One Cleanlist call routes the record across 25+ providers and normalizes every response into one schema
Billed per result: 1 credit for a verified email, 10 for a phone, 11 for both, nothing on a miss
Billing follows results, so a re-dispatch of the same record can be charged again: poll the identifier you already hold
Every v2 endpoint, its credit price and the published rate limits are listed on the Cleanlist enrichment API page at /product/api
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 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 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 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 v2 endpoint and what it costs.
What does a data enrichment API cost?
- ●Per result, not per call: Cleanlist charges 1 credit for a verified email, 10 for a direct dial, 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 access starts on the Pro plan at $229 a month for 5,000 credits. Scale is $599 for 15,000. The 14-day Scale trial carries 250 credits and 3 seats but excludes the public API and the MCP server. See pricing.
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 publishes its exact ceilings, its polling contract, and the honest list of what the v2 API does not do on the Cleanlist 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 that is a verified work email, a direct dial or mobile, 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 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 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 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 500-Lead Enrichment Benchmark, 2026, that cascade returned a verified email for 98% of 500 stratified B2B leads and a direct dial 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]
Frequently Asked Questions
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 follows exactly this split, and the endpoint names, request bodies and polling contract are documented on the Cleanlist 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 publishes its exact ceilings and its polling contract on the Cleanlist API page at /product/api.
How much does API enrichment cost per record?
+
Cleanlist bills per result rather than per call: 1 credit for a verified email, 10 for a direct dial, 11 for both, and nothing when a lookup returns no data. API access starts on the Pro plan at $229 a month for 5,000 credits; Scale is $599 for 15,000. 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 enrichment routes is documented on the Cleanlist API page at /product/api.
Where to next
Related terms
- Data EnrichmentData enrichment is the process of enhancing existing data records with additional information from external sources, improving accuracy, completeness, and usefulness for sales and marketing teams.
- Waterfall EnrichmentWaterfall enrichment is a data enrichment strategy that routes each record through a sequence of data providers, moving to the next source only when the previous one fails to return a match.
- 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 enhancing individual contact records with additional professional and personal data points such as job title, phone number, LinkedIn profile, and company affiliation from external data sources.
- Reverse ETLReverse ETL is the process of syncing data from a central data warehouse or [data lake](/glossary/data-lake) back into operational tools like CRMs, marketing platforms, and sales engagement systems where teams can act on it.
Compare & Choose
One endpoint, 25+ providers behind it
POST an email, a domain, or a LinkedIn URL to the Cleanlist v2 API and get a verified, normalized record back. Billed on results, so a miss costs nothing. API access starts on the $229 Pro plan. The 14-day Scale trial carries 250 credits and 3 seats and lets you test the data in the dashboard first.