Contact Enrichment API

Fill the gaps in a contact record — find missing emails and phone numbers, enrich by email or LinkedIn URL, and populate AI custom fields.

Coming soon

Still marked Coming soon in Reply's API reference as of 2026-07-05 (targeted late July 2026) — check docs.reply.io for current status.

Base URL: https://api.reply.io/v3
Official reference: docs.reply.io/api-reference/contact-enrichment/enrich-contacts-by-email
OpenAPI: contact-enrichment.openapi.yaml
Markdown twin: contact-enrichment.md
Scopes: contacts:readcontacts:operate

What it does

The Contact Enrichment API fills incomplete contact records in place. Reply’s API reference lists five operations in the group, all marked Coming soon (re-verified 2026-07-05; targeted late July 2026):

Enrich contacts by email — hand over an email address, get back a filled contact record.
Enrich contacts by LinkedIn URL — same result, keyed by a LinkedIn profile URL instead.
Find missing email addresses — resolve emails for contacts already in Reply that lack one.
Find phone numbers — resolve direct dials for contacts ahead of a call step.
Fill AI custom fields — populate AI-generated custom fields on contacts, ready to use as merge variables.

The adjacent Email Validations group is live today: Estimate email validation (scope contacts:read) and Schedule email validation (scope contacts:operate) verify deliverability of the addresses enrichment finds, before they enter a sequence.

The problem it solves

Waterfall enrichment is usually a separate vendor and a separate loop: export contacts, upload them to the enrichment tool, wait for the waterfall to run, download a CSV, re-import it, and map fields back onto your records. Every hop is a place where an agent pipeline stalls or drops data.

This API collapses that loop. An agent hands over what it knows — an email or a LinkedIn URL — and gets a filled contact record back inside the same platform that runs the outreach. Discovered emails, phone numbers, and AI field values land directly on the Reply contact, so the next step (validate, sequence, call) reads them with no export/import round-trip, no field mapping, and no second vendor API key.

How an agent starts using it

Honestly: not yet, for the enrichment operations themselves. All five are still marked Coming soon in Reply’s API reference as of 2026-07-05 (targeted late July 2026) — treat every path and field name on this page as indicative until the reference publishes the final shapes.

What an agent can do today:

Wire up email validation now. Estimate email validation (scope contacts:read) previews a run; Schedule email validation (scope contacts:operate) executes it. This is the live half of the fill-the-gaps loop.
Provision scopes. The Coming-soon enrichment lines carry no scope in the index yet. Since enrichment writes to contact records, scopes are expected to follow the contacts domain — exactly as the sibling Email Validations operations do (contacts:read, contacts:operate). A key provisioned for the contacts domain should be positioned for launch.
Watch the reference. Poll docs.reply.io for the contact-enrichment group; when the Coming-soon warnings drop, the operations above go live with their final request and response schemas.

Platform limits apply as everywhere else: 100 requests/minute and 3,000 requests/hour per user, with Retry-After on 429.

Typical agent tasks

Enrich a contact from a bare email address before writing a personalized opener
Enrich a contact from a LinkedIn URL when no email is known yet
Find missing email addresses for a batch of contacts before sequencing them
Find phone numbers for contacts ahead of a call step
Fill AI custom fields used as merge variables in outreach messages
Estimate, then schedule, email validation on found addresses before sending

Inputs

Name	Type	Required	Description
`emails`	string[]	no	Lookup keys for Enrich contacts by email — one or more addresses per call. Exact request shape publishes when the endpoint goes live.
`linkedInUrl`	string	no	Lookup key for Enrich contacts by LinkedIn URL — the path when an agent has a profile but no email.
`contactIds`	integer[]	no	Existing Reply contacts to run Find missing email addresses, Find phone numbers, or Fill AI custom fields against.
`customFieldIds`	string[]	no	Which AI custom fields to populate via Fill AI custom fields.

Outputs

Name	Type	Description
`contact`	Contact	The filled contact record — discovered emails, phone numbers, and populated AI custom fields land directly on the contact in Reply.
`status`	string	Per-contact enrichment outcome (e.g. enriched, not found). Field names are indicative until the endpoints go live.

Authentication

API key as Bearer token. Send Authorization: Bearer <API_KEY> on every request. Get an API key in the Reply.io app under Settings → API Key — authentication reference.

Rate limits

100 requests/minute and 3,000 requests/hour per user (shared across all of the user's API clients). On 429, honor the Retry-After header.

Example

Request — POST /v3/contact-enrichment/enrich-by-email

curl -X POST https://api.reply.io/v3/contact-enrichment/enrich-by-email \
  -H "Authorization: Bearer $REPLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "emails": ["[email protected]"] }'

Response — 200

{
  "items": [
    {
      "contactId": 90514382,
      "email": "[email protected]",
      "status": "enriched"
    }
  ]
}

Error — 403

{
  "type": "https://docs.reply.io/api-reference/authentication",
  "title": "Forbidden",
  "status": 403,
  "detail": "This API key does not have a required scope for this endpoint."
}

Related APIs

Modules are designed to chain — combining them is the point.

Prospect Search API

Search Reply Data — 1B+ contacts and 60M+ companies — by ICP filters like job title, seniority, department, industry, and location, and turn the matches into a prospect list.

Coming soon

Contact Data API

The CRM-grade contact and account store — create, import, filter, and organize the people and companies your agent works.

Email Validation API

Estimate and schedule email validation for contacts before sending — protect deliverability by never emailing dead addresses.

docs.reply.io ↗

Frequently asked questions

Should I enrich by email or by LinkedIn URL?

Use whichever key you have. Both operations resolve to the same filled contact record — enrich by email when a form or CRM gave you an address, enrich by LinkedIn URL when prospecting surfaced a profile with no email. Both are still marked Coming soon in Reply's reference as of 2026-07-05 (targeted late July 2026).

Does enrichment consume credits?

The API reference does not yet publish credit or billing details for these endpoints — they are listed as coming soon, so check docs.reply.io at launch. For validation, the live Estimate email validation endpoint exists precisely so an agent can preview a run before scheduling it.

How does this relate to email validation?

Enrichment finds addresses; validation verifies they are deliverable. The Email Validations endpoints are live today — Estimate email validation (scope contacts:read) and Schedule email validation (scope contacts:operate) — so an agent can validate found addresses before contacts enter a sequence.

Start here: get an API key and make your first call, or explore workflows that combine this module with others.