Skip to content

Email Enrichment

Request

Enriches contact records with email address data using multiple data sources.

Overview

The Email Enrichment API enriches contact records with email address data using multiple data sources. The service uses various lookup methods to find professional email addresses for contacts based on their name and company information.

Request Body

  • record_id: Your unique identifier for this record (required) - used for caching and duplicate detection
  • first_name: Contact's first name (required)
  • last_name: Contact's last name (required)
  • company: Company name or website URL where the contact works (required)
  • domain: Company domain (optional) - if not provided, will be extracted from company field
  • linkedin: Contact's linkedin url (optional) - improves lookup accuracy when available
  • max_credits: Maximum credits to spend on this request (optional, defaults to your account limit)

Request Constraints

  • Single record per request
  • Must include record_id, first_name, last_name, and company
  • record_id must be unique per contact record in your system
  • domain is optional but improves accuracy when provided
  • linkedin is optional but improves accuracy when provided
  • max_credits must be a positive integer if provided

Response Fields

  • success: Boolean indicating request success
  • record_id: Echo of the input record ID
  • first_name: Echo of input first name
  • last_name: Echo of input last name
  • company: Echo of input company
  • email: Professional email address or null if not found
  • confidence: Confidence level (high, medium, low) or null
  • credits_consumed: Number of credits used for this request
  • credits_remaining (int | null): Approximate remaining credit balance. Use GET /v1/credits/remaining for precise value.
  • processing_time_ms: Time taken to process the request in milliseconds
  • cached: Boolean indicating if this result was returned from cache (no credits consumed if true)

Credit Usage

Email enrichment consumes credits based on the data sources queried:

  • Cached Result: 0 credits (if same record_id queried recently)
  • Email Search: 5 credits
Security
BearerAuth
Bodyapplication/jsonrequired
record_idstring(Record Id)required

Your unique identifier for this record

first_namestring(First Name)required

Contact's first name

last_namestring(Last Name)required

Contact's last name

companystring(Company)required

Company name or website URL where the contact works

company_domainstring or null(Company Domain)
Any of:

Company domain (optional)

string
linkedin_idstring or null(Linkedin Id)
Any of:

LinkedIn profile identifier/slug (e.g., 'john-doe-123456')

string
max_creditsinteger or null(Max Credits)
Any of:

Maximum credits to spend on this request

> 0
integer
curl -i -X POST \
  https://api-gateway.agenthq.withlantern.com/v1/enrich/email \
  -H 'Authorization: Bearer <YOUR_ApiToken_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "record_id": "string",
    "first_name": "string",
    "last_name": "string",
    "company": "string",
    "company_domain": "string",
    "linkedin_id": "john-doe-123456",
    "max_credits": 0
  }'

Responses

Success Response

Bodyapplication/json
successboolean(Success)required

Boolean indicating request success

record_idstring(Record Id)required

Echo of the input record ID

first_namestring(First Name)required

Echo of input first name

last_namestring(Last Name)required

Echo of input last name

companystring(Company)required

Echo of input company

emailstring or null(Email)
Any of:

Professional email address or null if not found

string
confidencenumber or null(Confidence)
Any of:

Confidence score (0.0-1.0) or null if disabled/not found

[ 0 .. 1 ]
number
credits_consumedinteger(Credits Consumed)required

Number of credits used for this request

credits_remaininginteger or null(Credits Remaining)
Any of:

Approximate remaining credit balance. Use GET /v1/credits/remaining for precise balance.

integer
processing_time_msinteger(Processing Time Ms)required

Time taken to process the request in milliseconds

cachedboolean(Cached)required

Boolean indicating if this result was returned from cache

Response
{
  "success": true,
  "record_id": "contact_001",
  "first_name": "John",
  "last_name": "Smith",
  "company": "Acme Corp",
  "email": "john.smith@acme.com",
  "confidence": "high",
  "credits_consumed": 3,
  "credits_remaining": 950,
  "processing_time_ms": 750,
  "cached": false
}