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

The four contact-lookup endpoints (enrich by email, enrich by LinkedIn URL, find missing emails, find phone numbers) are marked Coming soon in Reply's API reference, targeted late November 2026. Filling AI custom fields now runs through two Custom Fields operations, preview and enrich, also Coming soon and targeted early October 2026. Verified 2026-10-02.

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 six operations for filling the gaps, all marked Coming soon (re-verified 2026-10-02). The four lookups in the Contact Enrichment group are targeted late November 2026; the two AI custom field operations, which sit in the Custom Fields group, are targeted early October 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.
Enrich contacts with an AI custom field – POST /v3/custom-fields/{id}/enrich fills one AI custom field across up to 1,000 contacts per call (or every contact you own), queued to run in the background at one credit per enrichment. Contacts that already hold a value are skipped unless you ask to regenerate them, and the values are ready to use as merge variables.
Preview an AI custom field – POST /v3/custom-fields/{id}/preview shows what the field’s prompt, or a draft prompt you are trying, produces for one contact. Nothing is written to the contact, and previews draw on a free daily allowance.

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 six are still marked Coming soon in Reply’s API reference as of 2026-10-02 (the AI custom field pair targeted early October 2026, the four lookups late November 2026). The lookups still carry placeholder request shapes there, so treat their paths and field names on this page as indicative until the reference publishes the final shapes; the AI custom field pair is fully specified, just not callable yet.

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 four lookups carry no scope in the reference yet; the AI custom field pair already requires contacts:operate. Since enrichment writes to contact records, the lookups are expected to follow the contacts domain too, 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.
Fill custom fields with AI today. Prompt Actions on the Contact Data API are live: save a prompt whose outputs map to custom fields, then run it over a batch of contacts; Reply credits are reserved up front for the contacts a run accepts.

Platform limits apply as everywhere else: 100 requests/minute, 3,000 requests/hour, and 150,000 requests/week 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 an AI custom field across a batch of contacts, ready to use as a merge variable in outreach messages
Preview an AI custom field on one contact before filling it across the rest
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 or Find phone numbers against, or to fill with an AI custom field (up to 1,000 per call; the field's id goes in the path).
`promptText`	string	no	A draft prompt to try in Preview an AI custom field instead of the field's saved prompt.

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, 3,000 requests/hour, and 150,000 requests/week per user (shared across all of the user's API clients). On 429, honor the Retry-After header.

Example

Request: POST /v3/contacts/enrich-by-email

curl -X POST https://api.reply.io/v3/contacts/enrich-by-email \
  -H "Authorization: Bearer $REPLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "emails": ["jane.doe@acme.com"] }'

Response: 200

{
  "items": [
    {
      "contactId": 90514382,
      "email": "jane.doe@acme.com",
      "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 add the matches straight into your prospect lists or a sequence.

Available

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-10-02 (targeted late November 2026).

Does enrichment consume credits?

For AI custom fields, yes: Reply's reference says each enrichment costs one credit, and previews draw on a free daily allowance. The four lookups do not publish credit details yet; 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.