Data Enrichment API: Endpoints, Fields and Matching Rules
A reference to data enrichment API endpoints, sample payloads, matching logic, latency, quality metrics and how to choose a provider for GTM teams.
In a 2024 global study of 631 CRM users and stakeholders in the United States, United Kingdom, and Australia, 31% of administrators said poor-quality data cost their organizations at least 20% of annual revenue, according to Experian's CRM data quality report. That isn't a cleanup backlog. It's what happens when routing, personalization, and forecasts run on records nobody can defend.
A data enrichment API takes a thin identifier and returns the attributes a revenue team needs before anyone is contacted. Treat every call as a matching and provenance decision, not a field-filling exercise. Score completeness and accuracy apart, and judge the work by qualified-meeting yield, not by match rate alone.
Outbound teams usually send from Instantly, run LinkedIn steps in HeyReach, and time the first touch with Whitewhale. None of those tools can repair a wrong company or a stale title. The API has to earn trust before a sequence starts.
Table of Contents
Data Enrichment API Endpoints and Fields at a Glance
A data enrichment API accepts a partial record, such as a domain, a company name, an email, or a person's name plus employer, and returns missing attributes such as industry, headcount band, location, job title, or technology stack. Providers, including Apollo, split that work into a few endpoint families. Compare inputs and returned fields, not the route name, because labels differ between vendors.
In a 2022 study of 1,241 CRM users across the United States, United Kingdom, and Australia, 50% had lost new sales because of inaccurate or incomplete CRM information, according to the Validity CRM data management study. The table below maps each family to the outbound job it serves.
Endpoint | Input | Returned Fields | Typical Use |
|---|---|---|---|
Company enrichment | Domain or company name | Industry, headcount band, revenue band, HQ location, funding stage | Account selection and segmentation |
Person enrichment | Email, or name plus company domain | Job title, seniority, function, business email status | Persona targeting and personalisation |
Email finder | First name, last name, company domain | Candidate email addresses with confidence value | Building contact lists |
Email verification | Email address | Syntax, domain and mailbox status | Protecting sender reputation |
Technographic lookup | Domain | Detected software by category | Tool-based targeting |
Bulk job | File of records | Job ID and downloadable results | Refreshing whole databases |
Company enrichment drives account selection. Person enrichment drives persona and personalization. The finder builds the list, and verification protects the domain you send from.
RFC 5322 defines an addr-spec as a locally interpreted string, an at-sign, and a domain. The local part may be a quoted string or a dot-atom. A check that only looks for @ creates false positives. A check that rejects every unusual but legal local part creates false negatives. Separate syntax from domain, mailbox, and deliverability checks, and keep the original address when you score it.
Technographic lookup supports tool-based targeting. A bulk job accepts a file, returns a job ID, and delivers results later, which is how you refresh a database without blocking the CRM.
A field marked unavailable for a market is a coverage gap to log, not a null to ignore. If Singapore headcount comes back blank while the US figure is full, record the gap before you treat the account as small. Teams wiring similar contracts can browse the recruitment API reference to see inputs, outputs, and error cases written down. Payloads show the shape of a response. Matching decides which record you trust.
Sample Request and Response Payloads
Send a small POST body: the domain or email, the fields you asked for, and a client reference ID that maps the answer back to the CRM row. Don't let the provider invent your primary key.
A useful response isn't a flat bag of strings. The JSON-LD specification uses @id as an IRI for the entity, and @type plus @context to map short names onto shared vocabulary. Compact JSON can follow the same idea.
Those values are illustrative, not from a named vendor. Ask for the documented schema before you build.
What each field is for
entity_id is the deduplication key across CRM, prospecting, and sequencing. Source-specific IDs can sit beside it. One person, one company, one join.
match.status and match.score gate sequencing. A high score on the wrong status still stays out of the queue.
sources and observed_at show where a value came from and whether it is current. The VP of Sales title above rests on two sources inside a 180-day window. Treat each source as an assertion, not as truth.
expires_at is the re-enrichment trigger. When that date passes, the field is stale even if it still looks tidy.
schema_version protects integrations when a vendor renames a band or adds a field. Pin the version and keep old readers working.
Practical rule: Store source and observed date on every field so a later audit can rebuild the record without guessing.
Errors and disagreements
A rate-limited call returns HTTP 429 with retry_after in seconds. An invalid domain returns HTTP 422 with a reason code. Retry or log. Never write an empty company into the CRM.
When providers disagree, keep every candidate with its sources. Apply a written order, such as verified contact data over scraped web data. A newer observed_at wins only when source tiers are equal. Never overwrite a verified field with an inferred one.
Matching Logic and Match Keys
An enrichment lookup is a matching decision, and the output is only as trustworthy as the match. NIST SP 800-63A describes identity resolution as deciding whether supplied attributes correspond to one unique individual in a defined population, and it says to collect only the minimum needed. Exact matching is often inadequate, so variation-aware rules are allowed, but those rules must be documented for the people who rely on them.
Separate match inputs from the enrichment fields you return. The API should answer with a machine-readable status: matched, ambiguous, unmatched, or suppressed, plus a score, the keys that fired, and reason codes.
Normalise inputs. Lowercase domains, strip tracking parameters, standardise country names, and drop legal suffixes such as Pte Ltd or Inc.
Try deterministic keys. A verified domain, a normalised business registration number, or a provider entity ID either hits one record or it doesn't.
Score probabilistic matches only if those keys fail. Use company name, address, website, and person role, which are weaker signals.
Assign one status.
matchedmeans a single candidate cleared the bar.ambiguousmeans two or more did.unmatchedmeans none did.suppressedmeans an opt-out or suppression list applies.
Person-level confidence and company-level confidence stay separate. A correct company doesn't validate the contact pinned to it. NIST allows one-to-many identification for resolution or deduplication only with a privacy risk assessment, and it specifies a 1:1,000-or-better false-positive threshold in that context. For outbound, the control is simpler: ambiguous rows never enter sequencing. They go to a review queue with a deadline. Every result should also support suppression, deletion, retention limits, and a reprocess when source data changes. How that lands in the CRM is covered in our note on data enrichment and CRM hygiene.
Starting points to tune, not universal laws: auto-accept company matches above 0.90, and person matches above 0.95. Common names and shared domains should sit higher.
Match Key | Strength | Typical Use |
|---|---|---|
Provider entity ID | Very high | Re-running enrichment on a known record |
Verified domain | High | Company-level matching for B2B accounts |
Business registration number | High | Legal entity matching in regulated markets |
Normalised email address | High for person matching | Contact-level matching when an email is known |
Company name plus country | Medium | Fallback when no domain is available |
Person name plus company domain | Medium | Person lookup; common names need extra attributes |
Job title and address alone | Low | Supporting evidence only, never a sole match key |
Deterministic keys come first because they don't ask you to guess. A job title plus a street address can support a decision. It can't make one.
Ambiguous means "two plausible people," not "close enough to email."
Latency, Rate Limits and Coverage Trade-offs
Speed, coverage, and cost pull against each other. Pick a mode per workflow, not one mode for the whole stack.
Synchronous single lookup: Returns in seconds, using only sources that answer immediately. Coverage is lower. Use it for a form fill or a new CRM record that must be routed within the next minute.
Asynchronous bulk job: Results arrive in minutes to hours. Coverage is usually higher because the provider can run deeper matching. Use it for lists of thousands.
Scheduled refresh: A weekly or monthly batch re-checks rows whose
expires_athas passed, so active accounts don't age in silence.
Mode | Speed | Coverage | Best Use |
|---|---|---|---|
Synchronous single lookup | Seconds | Lower, only immediately available sources | Form fills and new CRM records routed within a minute |
Asynchronous bulk job | Minutes to hours | Higher, deeper matching by the provider | Lists of thousands of records |
Scheduled refresh | Batch, weekly or monthly | Re-checks records whose expires_at has passed | Keeping active records current |
Most APIs cap requests per second or per day. When you cross the cap you get HTTP 429. Queue the work and retry with exponential backoff instead of hammering the endpoint. A clear public write-up of how caps, headers, and retries are documented is the RealtyAPI.io rate limit reference. Cache the response and reuse it until expires_at, or you pay twice for the same fact and add delay for nothing.
A small speed and coverage test
Run the same 500 records through synchronous and bulk modes. Compare populated-field rate per second and per credit spent. APAC coverage often differs from North America, so break the result out by country. A global average will hide a weak market.
Enrich synchronously only what must be routed within the next minute. Batch everything else.
Measuring Completeness, Accuracy and Freshness
A single match rate hides the failures that break outreach. NIST's data quality material defines completeness as how fully information is captured against a potential of 100%, and it treats accuracy as information that is correct and factual. A lead can hold every requested field and still name an outdated employer. It can also name a verified company and title and still have no usable channel.
One summary of B2B contact data puts annual database decay at 25–30%, as noted by Security Boulevard. A matched person can be the wrong person to email by the time the sequence runs. Report field-level coverage and correctness apart. Don't collapse them into one score.
Metric | What It Measures | How to Calculate |
|---|---|---|
Populated-field rate | Share of requested fields returned | Populated fields divided by requested fields |
Verified-field rate | Share of returned fields confirmed by a second source or check | Verified fields divided by populated fields |
Stale-record rate | Share of records past their expires_at date | Expired records divided by active records |
Conflict rate | Share of fields where providers disagree | Conflicting fields divided by fields compared |
Match precision | Share of accepted matches confirmed correct on a sample | Correct accepted matches divided by sampled accepted matches |
Meeting yield per verified record | Qualified meetings generated per verified record contacted | Qualified meetings divided by verified records contacted |
How to sample
Each month, pull a random sample of about 200 accepted records. Check them by hand or against a second source, and log errors by field. Segment by market, persona, record age, and channel. A strong populated rate in one country can sit next to a weak rate in another, and a blended number will not show it. The same split is what separates good data from bad data once the list is live.
Keep factual fields and model-generated predictions, such as inferred seniority or an intent score, in separate columns. A confident prediction can help you prioritise. It isn't a verified fact you can put in a sentence or a compliance file.
If a metric falls under the threshold you agreed, pause that segment. Don't stop the whole pipeline.
Provenance, Consent and Deletion Requirements
Bought B2B contact data isn't exempt from privacy duties. When a field describes a person, purpose limitation, transparency, minimisation, accuracy, security, and storage limitation still apply. EU working material on AI and personal data is clear that processing for AI has to meet those GDPR duties, and data preparation includes cleaning, updating, enrichment, and aggregation.
Most API write-ups stop at "send a domain, get a title." They skip what happens when the title was scraped, repurposed, or inferred. A confidently inferred job title needs a different label from a verified one. Confidence isn't lawful basis.
What to store on each field
For every returned attribute, keep the source, the collection date, the processing purpose, lawful-basis metadata, and the retention rule. Without that set, you can't answer a basic buyer question: which enriched fields selected or contacted this person?
Regional rules don't travel as one setting. EU processing constraints and APAC privacy laws differ by country, and some markets expect processing to stay in-region. Channel rules sit beside the data rules. Our overview of email marketing laws is the place to check before a sequence uses an enriched address.
Deletion has to leave the vendor
Individuals can ask for correction of inaccurate or incomplete personal data. Organisations generally must respond without undue delay and, in principle, within one month, and if the data was passed to others those parties must be told unless that is impossible or disproportionate, as set out in the European Commission's guidance for individuals.
Use one record ID in the enrichment store, the CRM, marketing automation, analytics, and any downstream list. A suppression that stops at the vendor copy leaves the person in the sequence. Propagate opt-outs with timestamps. Set retention per field type. Keep an audit log of who changed what, and when.
This is an engineering checklist, not legal advice. Review it with counsel for each market you will contact.
Choosing a Provider Against Clear Criteria
No single provider wins in every market, so choose by criteria weighted to your targets.
Coverage in your markets and personas (20%). A strong US file doesn't prove Japan or Indonesia.
Field accuracy from your sample (25%). This outweighs a homepage match rate.
Provenance and schema (15%). You want a source per field,
expires_at, and versioning.Compliance controls (15%). Deletion has to propagate, and regional processing has to be real.
Latency and rate limits (10%). They must fit the mode you run.
Cost per successful enriched record (10%). Failed lookups often still spend credits.
Integration effort (5%). CRM and sequencing connectors, not a slide.
Score each provider from 1 to 5, multiply by the weight, and write the reason in a shared sheet. A claimed match rate is a marketing figure until you reproduce it on your own rows. Side-by-side notes such as ZoomInfo alternatives for B2B prospecting help you see how vendors describe themselves. They don't replace your sample. A longer vendor map lives in our data enrichment tools write-up.
Red flags in the docs
Walk away, or at least don't automate, when you see no documented schema, no match status, no expiry dates, a vague line about "multiple sources," or coverage with no country split. Those gaps show up later as bad meetings, not as a low score on a spreadsheet.
Run a One-Week Enrichment Pilot Before You Commit
A week of your own records beats a demo dataset.
Pull 300 to 500 records that match your current ICP, mixed across the markets you will sell into, including APAC countries if they are in scope.
Run the same rows through two or three providers in the same week so freshness is comparable.
Score each output on the weighted criteria, logging completeness and accuracy apart.
Review 50 disagreements by hand. Note the cause: a stale source, the wrong company, or the wrong person.
Set match thresholds, quarantine rules, and suppression behaviour before any sequencing starts.
Map each field into the CRM with its source and
observed_atstored beside the value.
Continue with the provider that clears your thresholds in your markets. Use a hybrid, one vendor for contacts and another for firmographics, only when the pilot shows that no single provider clears both in every target market. Write that reason on the scoring sheet. List work of this kind follows the same discipline as lead generation list building: define who belongs, then verify, then rank.
We can walk through a customized scoring matrix and a pilot plan for a single vendor or a hybrid. On a discovery call, we show how we would find the buyers, build the system, and generate pipeline, and we train the sales team to run it so the results continue after the build.
The Social Search designs outbound systems for B2B teams selling into APAC and beyond, including enrichment, verification, and routing into sequences you own. If you want that matching and provenance model applied to your ICP, visit The Social Search and book a working session on your own records.
