Email Enrichment API: Test Identity Before Writeback

An email enrichment API takes one address and returns the person and company behind it, which sounds deterministic and is not. Addresses are reused, shared, aliased, and abandoned, and the vendor that handles those cases honestly is worth more than the one with the broadest coverage. The condition that changes your requirements is what you do with the result: enrichment feeding a research brief can tolerate ambiguity, while enrichment feeding an automated CRM write cannot.

Treat the Address as Evidence, Not as an Identity

A work email usually identifies one person at one company at one point in time. Each part of that sentence fails often enough to design around.

Addresses get recycled when an employee leaves and a successor inherits the mailbox. Aliases route several addresses to one human. Shared and role-based mailboxes belong to a function. Personal addresses carry no company signal at all. Catch-all domains accept anything, so an address that appears valid may never have belonged to anyone.

An enrichment API that returns a confident person for every one of those cases is not more capable, it is less careful. Build your test set from exactly these situations rather than from clean corporate addresses that any vendor resolves.

The last row is the sharpest test. Several people named the same thing at one large employer is the classic collision, and a vendor's behavior there predicts its behavior across your whole list.

Read the Endpoint Shape Before the Coverage Claims

Vendors structure this work differently, and the split between endpoints tells you which part of the problem each treats as separable.

Hunter's API documentation splits the job into three endpoints. The person lookup at GET /v2/people/find takes an email or a linkedin_handle, with the handle taking precedence when both are supplied, and returns name, location, time zone, geographic detail, employment fields including domain, title, role, and seniority, plus social handles. Company lookup runs through GET /v2/companies/find, which takes a required domain and returns attributes including category, employee metrics, and technology stack. For both at once, GET /v2/combined/find takes a required email and returns the person and company objects together. All three are documented at 15 requests per second and 500 requests per minute.

Two response fields in that set matter more than the attribute list. The fuzzy field indicates matching confidence, which is your threshold input. The activeAt and inactiveAt timestamps describe account activity, which is your staleness input.

Apollo's people enrichment endpoint accepts hashed_email in MD5 or SHA-256 format alongside the plain email parameter. That option is worth raising with your legal and security reviewers early, because it lets you resolve identity without sending raw addresses to a third party. Apollo also documents that no match consumes zero credits and that no demographic credit is charged when match_confidence is none, which gives you both an abstention signal and an aligned billing model.

Our view: treat any provider that returns a person for a role address without flagging it as failing the evaluation outright. That behavior indicates the matching layer is optimizing for response rate, and every downstream decision inherits the error.

Separate Person Context From Company Context

The combined response is convenient and it hides a distinction that matters during writeback.

Company context derived from a domain rests on a strong key, since a domain maps to one organization far more cleanly than an address maps to one person. Person context derived from an address is a resolution judgment. Writing both at the same confidence level means your firmographics and your person fields carry the same implied certainty when they do not deserve it.

Store them separately with their own confidence values and their own observation dates. Then set different thresholds for each. A workable pattern is to accept company context at moderate confidence because the cost of a small error is low, and to require high confidence for any person field that will appear in a message.

This also handles the personal-address case cleanly. An address at a consumer mail provider yields a person with no employer, and a system that stores the two contexts separately simply leaves the company fields empty instead of guessing.

Design the Writeback to Be Reversible

The failure that costs real money is not a bad match, it is a bad match written over something good with no way back.

Classify every CRM field before the first sync: the API owns it, a human owns it, or the API fills it only when empty. Suppression status, opt-out flags, rep-authored notes, and negotiated terms belong to humans permanently. Title, seniority, and company attributes can reasonably be API-owned when they carry provenance.

Make the operation idempotent so running the same job twice produces the same end state and not two audit entries. Test this by running your pilot batch twice and comparing field history.

Then rehearse the rollback before you need it. Keep the raw response, the request that produced it, and a timestamp in a store outside the CRM. Pick a pilot batch, restore prior values from that record, and confirm the CRM returns to its earlier state. A rollback path that has never been executed is an assumption.

Rate limits shape the design too. Hunter's documented 15 requests per second and 500 per minute supports real-time enrichment at form submission and requires scheduling for a large backfill. Decide what happens when a limit is hit or the provider is unreachable, and make the default fail closed: queue the record, change nothing, and alert.

LeadHaste practice: we keep an evidence table holding every raw enrichment response with its request and timestamp, separate from the CRM. When a rep disputes a title, that table answers the question in seconds and tells us whether the fault was the vendor or our threshold. It is our operating rule, not a provider feature.

Price the Unit You Actually Consume

Compare on cost per usable record, where usable means the match cleared your threshold, carried the fields you needed, and survived suppression.

cost per usable record = total spend / records above threshold that passed suppression

Run suppression ahead of the API call wherever your data allows it. Enriching an address you were never permitted to contact spends credits to create a liability.

Settle the commercial questions that vary most across this category before signing: what defines a credit, whether a non-match is billed, whether unused credits expire, overage pricing, retention rights for enriched values after termination, and whether you may store responses in your own warehouse. That last permission is what makes an audit possible months later, and it is not universal.

Run the Acceptance Test

1. Build the test set from collisions, aliases, role addresses, and catch-alls
2. Record the response for each and grade abstention as a correct answer
3. Set separate confidence thresholds for person and company context
4. Verify observation dates exist on employment fields
5. Run the pilot batch twice and confirm identical end state
6. Execute a rollback and confirm prior values return
7. Re-run the set after 30 days to measure decay

Step two is the one that changes purchasing decisions. A vendor that abstains on your six hard cases and resolves everything else is a better foundation than one that answers all six confidently and is wrong about two. For the person-resolution version of this problem, see our lead enrichment API guide, and for account-level fields the data enrichment API buyer's test.

We can build the hard-case test set, set the thresholds, and design the reversible writeback with your team during a free ICP and campaign-fit discovery call. Book your free ICP and campaign-fit discovery call →