People Enrichment API: Fields, Routing, and Scoring

Your enrichment job completed, the CRM accepted the updates, and the sales agent queued its next sequence. Then someone spots a contact assigned to a former employer, a reachable phone number attached to the wrong person, and an email marked valid without any explanation of what was checked.

The integration worked. The decision policy didn't.

A people enrichment API accepts partial identity information and returns additional person attributes. In production, treat those attributes as an unreliable data dependency, not a completed contact record. Your pipeline needs to know which person matched, where each value came from, what verification established, and whether the result permits the next action.

Table of Contents

• Mapping the Data Categories a People Enrichment API Returns
  • Identity and professional attributes
  • Contactability and professional profiles
• Matching Inputs to the Right Person
  • Normalize without destroying evidence
  • Read confidence alongside the evidence
• Reading Response Schemas, Status Fields, and Errors
  • Core Response Field Groups and Their Purpose
  • Build retries around a documented error contract
• How Multi-Provider Waterfall Routing Behaves
  • Trace a lookup through its decisions
  • Keep routing and billing independently auditable
• Comparing Enrichment Approaches and Where RichAPI Fits
  • Compare the operational trade-offs
  • Evaluate the unified-interface option
• Deduping and Scoring Enriched Records
  • Merge evidence, not just columns
  • Score by action and attribute
• Governance, Consent, and Deletion Propagation
  • Check permission before retrieval
  • Propagate deletion beyond the CRM
• Making Enrichment Safe for AI Agents and Your Next Step
  • Put deterministic controls outside the model
  • Test action safety before enabling autonomy

Mapping the Data Categories a People Enrichment API Returns

Map the response into distinct categories before mapping it into CRM properties. Identity, employment, contactability, and social data answer different questions. Combining them into a flat object without attribute metadata makes it difficult to distinguish a reliable identifier from an inferred segmentation label.

The field names below describe a proposed internal schema, not a vendor-specific response contract.

Identity and professional attributes

Identity attributes include full_name, structured name components, and normalized variants used for comparison. A display value might preserve a person's capitalization and punctuation, while a separate comparison value supports matching without changing what sales representatives see.

Keep the derivation explicit:

• Observed names came from an identified source.
• User-supplied names came from a form, CRM entry, or another direct submission.
• Inferred variants were generated for comparison and shouldn't replace the original value.

This separation follows the emphasis on traceable identity evidence in NIST's digital-identity guidance. An enrichment pipeline should preserve what it received rather than converting a normalization decision into an identity claim.

Professional attributes describe a person's employment context. Group job_title, seniority, function, and employer under an employment object so related values remain associated.

For example, job_title might contain Director of Revenue Operations, while seniority contains a normalized leadership category and function identifies revenue operations. Treat the title as observed only when its source supports that designation. Seniority and function may be classifications derived from the title, so label them accordingly.

CRM assignment, persona segmentation, and sales-sequence selection depend on these distinctions. A classification can support segmentation without proving that the person currently holds the underlying role.

Contactability and professional profiles

Contactability fields include work email addresses and phone numbers, accompanied by their verification states. Preserve multiple candidates as separate attribute objects rather than stuffing them into a single string.

Social and professional profile fields hold profile URLs and source-specific identifiers. They can support research, identity reconciliation, or navigation to a professional profile, but a returned URL isn't interchangeable with a verified contact channel.

A CRM-oriented person record might therefore group:

Expect empty contact channels, missing classifications, and incomplete employment details. A provider may lack evidence, a requested attribute may fail verification, or policy may prevent disclosure. Don't interpret an empty value as proof that the person has no email, phone, or current employer.

Available fields depend on the endpoint and each attribute's verification state. Build parsing logic around that contract, not around the fullest response you encountered during testing.

Matching Inputs to the Right Person

A complete record for the wrong person is worse than an incomplete match. Establish identity before deciding whether any returned attribute belongs in your CRM.

Use a deterministic hierarchy, but don't confuse a strong identifier with permanent ownership. A phone number or email still needs relevant verification and contextual consistency.

Normalize without destroying evidence

Start with a normalized email address or verified phone number when available. Otherwise, combine a full name with employer domain, professional URL, geography, or job title. Send the smallest reliable set that distinguishes the intended person.

Keep normalization conservative:

• Names: Preserve the original spelling and script. Store comparison variants separately.
• Email addresses: Remove accidental surrounding whitespace and apply documented normalization rules. Don't rewrite addresses based on guesses.
• Phone numbers: Use a canonical international representation only when the country context is known.
• Domains and titles: Standardize comparison values while retaining the submitted employer and title text.

Consider a hypothetical pair of requests for Alex Morgan. The first includes an employer domain from your existing account record and a professional profile identifier; the second includes a different employer domain and different profile evidence.

The shared name doesn't justify merging the results. If the returned profiles align with their respective employers and identifiers, keep them separate unless additional evidence establishes that they represent a job change by the same individual. If the API returns the same candidate for both requests, flag the contradictory employer evidence rather than accepting both matches.

Read confidence alongside the evidence

Require your internal match object to expose matched_input_fields, match_confidence, and relevant evidence timestamps. These fields answer different questions: which inputs agreed, how the matcher assessed the result, and how current the supporting evidence is.

A confidence label without its definition isn't a merge policy. Ask whether it measures identity similarity, source agreement, or something else, then map it into your own acceptance rules.

Practical rule: Don't merge because the names match. Merge because the documented identity evidence passes your policy and no unresolved contradiction blocks it.

Use geography and title as supporting context, not substitutes for stronger identifiers. Those attributes can help distinguish candidates, but they shouldn't override a conflicting professional profile or verified contact identity.

When evidence falls below your documented threshold, return ambiguous_match internally and skip the merge. Preserve the candidate references and rejection reason so a reviewer can resolve the ambiguity without repeating the entire lookup.

Reading Response Schemas, Status Fields, and Errors

Separate request success, identity resolution, and attribute usability. A successfully processed lookup can still produce an ambiguous identity, an unusable contact channel, or an intentionally withheld field.

REST provides an established delivery pattern for sending machine-readable enrichment responses to CRMs, automation tools, warehouses, and agents. The historical review of REST adoption supplies the technical background, but transport compatibility alone doesn't make different vendors' schemas equivalent.

Core Response Field Groups and Their Purpose

The following groups describe a proposed normalization layer between the vendor response and your application.

Request fields explicitly. An identity lookup shouldn't automatically retrieve every available contact channel or social attribute.

Use a field-selection parameter or scopes such as identity, employment, contactability, and social. This keeps parsers focused and supports the data-minimization principle described in GDPR Article 5.

Email verification needs separate statuses for syntax, domain, mailbox, and reachability. If a provider reports only a combined result, preserve that limitation rather than manufacturing component-level certainty.

For nullable attributes, pair the value with an explicit reason such as not_found, not_verified, not_requested, or suppressed. Your parser should never need to infer the reason from an empty string.

Build retries around a documented error contract

For your own API boundary, use application/problem+json as the error representation. Require a stable problem type, readable detail, field-level validation information, a correlation identifier, retry guidance, and a billing outcome.

An illustrative validation-error body, expressed as fields rather than vendor syntax, could contain:

• type: A stable identifier such as invalid_identity_input.
• title: A short description of the validation failure.
• detail: An explanation that the supplied identity signals aren't sufficient.
• invalid_fields: The affected inputs and their individual problems.
• correlation_id: The identifier support and operators can trace.
• retryable: false, because the caller must change the request.
• billing_outcome: An explicit statement of whether credits were consumed.

Don't retry unchanged validation failures. Retry transient dependency failures only under a bounded policy that respects the returned guidance.

A timeout is a separate concern: the client may not know whether processing completed. Preserve the original request identity and reconcile its outcome before submitting another potentially billable lookup.

How Multi-Provider Waterfall Routing Behaves

A waterfall is a routing policy, not a guarantee of truth. The orchestrator tries relevant licensed providers in sequence and accepts a result only after it passes the configured checks.

The important distinction is first answer versus first acceptable answer. Stopping at the first nonempty payload defeats the purpose of verification.

Trace a lookup through its decisions

Consider a hypothetical work-email request based on an accepted identity and current employer evidence. The initial provider returns a candidate associated with an older employment record. Your acceptance policy rejects it because it doesn't satisfy the requested employment context.

The next provider returns no candidate. A later provider supplies an address that passes the required verification, so the orchestrator returns that result.

An internal execution log should make those distinctions visible:

These are illustrative log semantics, not a claim that every provider exposes those exact states. If a service doesn't expose its rejection reasons, record the visibility gap rather than inventing an explanation.

A data enrichment platform should be evaluated partly on whether operators can reconstruct these decisions, not just on whether it returns filled fields.

Keep routing and billing independently auditable

The service described here uses a consistent endpoint credit cost regardless of which provider fulfills the lookup. Email and phone misses don't consume credits, and results are returned only when verification passes.

Still, capture the reported billing outcome. Don't derive charges from provider-attempt counts or assume every empty response represents the same billable event.

A provider failure, a verified miss, and a policy refusal can all leave the contact field empty. They require different operational responses.

Persist request_id, endpoint, acceptance policy version, provider-attempt references, selected source, and final billing state. Keep sensitive candidate data out of general-purpose logs; retain only the evidence your governance policy permits.

When a representative questions a returned address, this log should show what the service attempted and what your pipeline accepted. Without it, the team can see the final field but can't explain the decision that put it there.

Comparing Enrichment Approaches and Where RichAPI Fits

Choose an enrichment approach based on the decisions your application needs to make. Returning more fields isn't automatically useful if your team can't verify their meaning or control writeback.

Manual research, a direct vendor integration, and a managed waterfall each move work to a different place. None removes the need for an acceptance policy.

Compare the operational trade-offs

Manual research can be precise when a researcher checks the right evidence, but it isn't always accurate. It suits ambiguous or high-consequence exceptions better than repetitive list processing.

A single source reduces moving parts. It's a reasonable choice when your evaluation shows that the vendor supports the fields and population your workflow needs. The trade-off is concentrated exposure to that source's gaps, outages, and stale attributes.

A waterfall adds fallback options, but more providers don't automatically mean independent evidence. Ask whether apparent agreement reflects distinct observations or repeated copies of the same underlying record.

Evaluate the unified-interface option

RichAPI is an option for teams that want a shared API key across REST and MCP access rather than separate provider integrations. It offers licensed-provider waterfall routing, fixed endpoint credit pricing without seat requirements or minimums, execution logs, and contact, company, social, and signal capabilities.

Its supported workflow tools include Clay, HubSpot, Zapier, n8n, and Claude. A bulk endpoint and asynchronous webhooks support larger jobs. Verify the exact response schema and log accessibility for the endpoint you'll use before designing around a capability described elsewhere in the service.

Keep person and account enrichment separate in your data model. A company enrichment API can supply account context, but matching a person to that account remains a distinct identity and employment decision.

Before choosing an approach, ask:

• Evidence: Can you inspect provenance for the attributes that drive automation?
• Failure handling: Can the integration distinguish misses, ambiguity, dependency failures, and suppression?
• Workflow fit: Does the delivery model suit interactive lookups, background jobs, or both?
• Ownership: Who reviews disputed matches and maintains the acceptance rules?

Deduping and Scoring Enriched Records

Deduplication happens after retrieval, when your pipeline reconciles candidate records with existing contacts. Don't reuse the provider's match score as a complete record-quality score. Identity confidence and operational usability are related, but they aren't interchangeable.

Build candidate clusters from normalized email, verified phone, and employer-domain-plus-name combinations. Treat the weaker combinations as review candidates rather than automatic merge authorization.

Merge evidence, not just columns

A merge should preserve attribute history and lineage. Keep source values, their observation times, and your selected canonical value separately.

Consider this hypothetical set of records for the same intended contact. The labels are illustrative internal grades, not provider scores or measured performance.

The name and supported contact identifier can reconcile into the same person entity when your merge policy allows it. The employer and title shouldn't be flattened into whichever record arrived last.

Store conflicting employment values with their sources. Select a current value only when your policy resolves the conflict using sufficient evidence. Otherwise, leave the current-role decision unresolved while retaining the person's accepted identity.

Score by action and attribute

Use separate assessments for identity_quality, employment_quality, and contactability_quality. A record may be suitable for account research but unsuitable for automated outreach.

Your scoring policy should evaluate:

• Match confidence: Whether the accepted identity meets the documented standard.
• Verification state: Whether the specific channel passes the checks required for its intended use.
• Source agreement: Whether consistent evidence supports the attribute.
• Freshness: Whether the observation remains recent enough for the decision.
• Conflict state: Whether unresolved contradictions block a particular action.

Writeback safeguard: Never let a newly returned inferred value silently overwrite a protected user-supplied field.

Keep observed_at distinct from retrieved_at. A lookup performed today can still return an older observation. The GDPR accuracy principle reinforces the need to keep relevant personal data accurate and rectify inaccurate values without undue delay.

Re-score on a schedule aligned with the workflow's risk, and when a source reports a relevant change. Store score_policy_version and the reasons behind the grade so an older record doesn't retain eligibility indefinitely because nobody recalculated it.

Governance, Consent, and Deletion Propagation

The most useful enrichment response may be a refusal. A suppressed result can prevent a disallowed lookup, an unwanted CRM update, or the reintroduction of a record your team already removed.

Maximizing returned fields is the wrong objective when the organization can't justify collecting or using them. Treat permitted processing as an input to the lookup, not a review performed after distribution.

Check permission before retrieval

Document the applicable lawful basis with privacy counsel for each market and use case. Don't assume that public availability, a provider contract, or technical access establishes permission for your intended processing.

Before calling the API, check the relevant controls:

• Purpose: Record why the workflow needs the requested attributes.
• Permission evidence: Consult applicable consent records or legitimate-interest assessments.
• Suppression: Block identities already marked against collection or outreach.
• Regional restrictions: Apply jurisdiction-specific handling rules.
• Retention: Associate the result with a deletion or review policy.

Carry permitted-use metadata with the record so downstream consumers don't mistake availability for authorization. A sales workflow and a recruiting workflow shouldn't inherit each other's permissions by default.

The operational difficulty is real. A study of personal-information removal services found that services correctly identified user records only 41.1% of the time, illustrating why identity verification matters in removal workflows as well as enrichment.

Propagate deletion beyond the CRM

Consider a hypothetical deletion request involving a CRM, an agent workflow's stored prompts, and an exported spreadsheet. Removing the CRM contact doesn't remove the other copies.

Create a deletion job that identifies the person, locates downstream destinations, sends removal instructions, and records acknowledgments. For the spreadsheet, assign an owner who can confirm removal rather than marking the job complete when an email notification is sent.

The process breaks when destination lineage is missing, exports have no owner, or logs preserve full enrichment payloads indefinitely. Prefer minimal operational logs and maintain a controlled inventory of where personal attributes were copied.

Use the publisher's opt-out route where applicable, but don't treat a provider-side request as proof that your own downstream copies have disappeared. Track those obligations independently.

A useful internal response model includes suppressed, policy_blocked, and stale_data outcomes. Those states should stop the relevant action without triggering a fallback intended to retrieve the same prohibited data elsewhere.

Controlled non-enrichment is a successful policy outcome. Record why the pipeline declined to enrich, expose the decision to authorized operators, and prevent scheduled jobs from undoing it on the next run.

Making Enrichment Safe for AI Agents and Your Next Step

An agent should consume enrichment as typed evidence, not as a paragraph of plausible biography. Give it the accepted values and explicit action permissions, while keeping the underlying evidence available for inspection.

This is a practical readiness issue. In Adobe's survey of B2B organizations, 75% identified data integration and quality as their biggest challenge for agentic AI.

Put deterministic controls outside the model

Don't ask the model to decide whether a provider's confidence label is sufficient for outreach. Evaluate that rule in application code, then expose a tool result containing the decision and its reasons.

For example, your internal contract can distinguish can_update_contact, can_route_by_role, and can_start_outreach. Each permission should be calculated from the relevant identity, attribute-quality, and governance rules rather than inferred from a generally successful lookup.

Give the agent explicit operating rules:

• Verified attributes: Use only within the verification scope the response establishes.
• Inferred attributes: Treat as classifications or candidates, not established personal facts.
• Deterministic nulls: Respect the accompanying reason. Never fill an empty personal field with a guess.
• Conflicting evidence: Pause the affected action and request review or approved revalidation.
• Stale employment: Recheck before using it to personalize or route outreach.

Provider-attempt logs and retrieval timestamps need to be available to code, not only visible in a dashboard. If the API doesn't expose them directly, determine whether you can retrieve an execution artifact and associate it with the tool result.

Test action safety before enabling autonomy

Use idempotency keys where the service supports them, and maintain your own action ledger for downstream effects. A retried lookup shouldn't automatically cause another CRM mutation or repeated outreach.

Add change detection before writeback. Compare the accepted attribute state with the version your last action used, then decide whether a meaningful change warrants an update. Don't let an older asynchronous result overwrite a newer accepted state.

Start with a small, representative sample of your own records through REST access. Include incomplete inputs, disputed employers, missing contact channels, and suppressed identities rather than testing only clean contacts.

Inspect the schema and execution logs before connecting an MCP server to an agent workflow. Check whether your code can explain every accepted field, blocked action, and reported charge. Then enable a narrowly scoped workflow, such as preparing contact updates for review, before permitting autonomous writes or outreach.

The acceptance test isn't whether the agent produces a convincing summary. It's whether the system reliably refuses actions the evidence doesn't support.

RichAPI offers unified enrichment through REST and MCP, with provider routing and execution logs for inspecting lookup outcomes. Visit RichAPI to set up access, test representative records, and validate your parsing and action policies before connecting enrichment to an autonomous workflow.