Skip to content

Person Enrichment

Request

Enriches person records with comprehensive contact and professional data.

Overview

The Person Enrichment API enriches person records with comprehensive contact information, professional details, and verification status. This service provides detailed person data including contact information, job titles, seniority levels, and email/phone verification status.

Request Body

  • record_id: Unique identifier for this enrichment request (required)
  • first_name: Person's first name (required)
  • last_name: Person's last name (required)
  • company_domain: Company domain where the person works (required)
  • email: Person's email address (optional)
  • linkedin_id: LinkedIn ID or profile URL (optional)
  • effort: Enrichment effort level (optional, default: low)
  • max_credits: Maximum credits to spend on this request (optional, defaults to your account limit)

Request Constraints

  • record_id, first_name, last_name, and company_domain are required
  • company_domain should be a valid domain format
  • email should be a valid email format 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
  • person: Enriched person data object containing:
    • full_name: Person's full name
    • email: Person's email address
    • email_confidence: Email confidence score (0.0-1.0)
    • email_status: Email verification status (valid, accept_all, risky, invalid, unknown)
    • phone: Phone number
    • title: Job title
    • linkedin_url: LinkedIn profile URL
    • job_last_seen_at: ISO timestamp when job information was last verified
  • confidence: Confidence score (0.0-1.0) or null if disabled/not found
  • 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

Email Status Values

  • valid: Email address is valid and deliverable
  • accept_all: Email server accepts all emails (catch-all)
  • risky: Email address may be risky or temporary
  • invalid: Email address is invalid or undeliverable
  • unknown: Email status could not be determined

Credit Usage

Person enrichment consumes credits based on the data sources queried:

  • Cached Result: 0 credits (if same person queried recently)
  • Person Lookup: 4 credits
Security
BearerAuth
Bodyapplication/jsonrequired
record_idstring(Record Id)required

Unique identifier for this enrichment request

first_namestring(First Name)required

Person's first name

last_namestring(Last Name)required

Person's last name

company_domainstring(Company Domain)required

Company domain where the person works

emailstring or null(Email)
Any of:

Person's email address

string
linkedin_idstring or null(Linkedin Id)
Any of:

LinkedIn ID or profile URL

string
effortstring(EnrichmentEffortType)

Enrichment effort type

Default:"low"
Enum:"low""medium""high"
max_creditsinteger, [ 1 .. 100 ](Max Credits)

Maximum credits to spend on this request

Default:1
curl -i -X POST \
  https://api-gateway.agenthq.withlantern.com/v1/enrich/person \
  -H 'Authorization: Bearer <YOUR_ApiToken_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "record_id": "string",
    "first_name": "string",
    "last_name": "string",
    "company_domain": "string",
    "email": "string",
    "linkedin_id": "string",
    "effort": "low",
    "max_credits": 1
  }'

Responses

Success Response

Bodyapplication/json
successboolean(Success)required

Boolean indicating request success

record_idstring(Record Id)required

Unique identifier for this enrichment request

personPersonEnrichmentData (object) or null
Any of:

Person enrichment data response.

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": "person_001",
  "person": {
    "full_name": "Jane Doe",
    "email": "jane.doe@trinet.com",
    "email_confidence": 0.93,
    "email_status": "valid",
    "phone": "+1-415-555-0199",
    "title": "Director, RevOps",
    "linkedin_url": "https://linkedin.com/in/janedoe",
    "job_last_seen_at": "2025-08-30T15:12:00Z"
  },
  "confidence": 0.9,
  "credits_consumed": 1,
  "credits_remaining": 950,
  "processing_time_ms": 1200,
  "cached": true
}