Accepted identifiers
Use the person enrichment API with email, phone, social profile URL, name and company, or other partial person identifiers.
Person APIs
Person Enrichment API
Submit one or more identifiers for a person (email, phone, social profile URL, or name) and receive enriched person data such as contact details, work history, social profiles, education, and location when available. At least one of email, phone, social_media_url, or name is required. The request is queued asynchronously and returns a request_id; poll the status endpoint or supply a callback_url. The completed result may include derived classifications and, when requested, a probability match-confidence field.
Manual credentials take precedence over your account key.
Overview
The Person Enrichment API resolves one or more identifiers into a complete person profile, giving teams a reliable way to append identity, work, education, contact, and social context to existing records.
Best for
- Completing CRM or CDP records
- Resolving a person from partial identifiers
- Adding work history, social profiles, and contact context
Returns
- Merged person profile data
- Contact and social fields when available
- Confidence-oriented identity resolution output
Implementation guide
Profile fields
Responses are built for identity resolution, contact enrichment, work history, education, public social profiles, and profile-level context.
Selective retrieval
Use Lookup Fields instead when you only need a narrow field set and want to avoid retrieving a full enriched person profile.
Parameters
email string optional
Validated for format.
phone string optional
Must normalize to a US 10-digit number or an international E.164 number.
social_media_url string optional
Profile URL.
name string optional
Person's full name. At least one identifier (email/phone/url/name) is required.
company string optional
Employer; aids matching.
city string optional
Location-based disambiguation for name lookups (max 100 chars). Common city abbreviations are understood.
callback_url string optional
If set, results are POSTed here. Must be a valid HTTP(S) URL on an allowed host when a callback allow-list is configured.
newsfeed array | string optional
Social sources to also pull. Choose one or more supported source literals, or the literal
"all" (cannot be mixed with named sources).ai_enhanced_search boolean optional
Enable AI-assisted search expansion.
e.g. true
strict_email_check boolean optional
Require stricter email-to-identity confirmation.
e.g. false
lite_enrich boolean optional
Use the lower-cost lite enrichment option and return a reduced field set.
e.g. false
probability_score boolean optional
Opt in to match-probability scoring. When available, the result includes a
probability field (high/medium/low). Use this score as context, not as the sole decision signal.e.g. false
force_organization_refresh boolean optional
Force a live refresh of the person's organization (employment) data. By default recently validated organization data is reused to keep responses fast; set this to
true to re-validate it live and return the most up-to-date company and title. Live validation adds processing time, so enable it only when you specifically need the freshest organization data.e.g. false
required_fields array optional
Field names the result must contain to count as a match (case-insensitive). Use the supported field literals shown below. With
lite_enrich, only core identity, company/title, and primary profile fields are available.Polling for the result
This endpoint is asynchronous. A successful submit returns a request_id while the job runs in the background. Poll the same path with a GET request - same authentication headers - passing the request_id as a query parameter:
Loading your API credentials...
Each poll returns the job's current status; once it is completed the payload carries the result shown under Responses. Polling an
unknown or expired request_id returns 404 request_not_found.
| Status | Meaning |
|---|---|
| queued · processing · pending | The job is still running - keep polling. |
| completed | The job finished; the payload carries the result and completed: true. |
| failed | Terminal - the job could not complete; the error field explains why. |
Poll every few seconds at first, backing off for long-running jobs. Polling is free - status checks never burn credits.
Prefer push delivery?
Supply the optional
callback_url parameter and the completed payload is POSTed to your endpoint
when the job finishes - no polling required. Delivery is retried up to 5 times with exponential backoff (1s,
5s, 15s, 1m, 5m) and a 30-second timeout per attempt; respond with a 2xx status to acknowledge receipt.Credit usage
Credits are charged based on the matched configuration. The listed cost is the per-result unit price.
| Feature | Credits | Notes |
|---|---|---|
| Person Enrichment | 6 | Charged only when usable data is returned |
| Lite Enrichment | 3 | lite_enrich: true - fewer credits for a reduced field set |
| No match | 0 | Empty results never burn credits |
Heads up
Empty results do not burn credits.
Responses
202 Enrichment queued - poll /person/enrichment with the returned request_id
400 Malformed JSON, missing identifiers, or an invalid field (e.g. invalid_newsfeed, invalid_required_fields - a field not available in lite mode)
401 Missing or invalid API credentials
402 insufficient_credits - not enough credits to complete the request
403 subscription_required or ip_not_allowed
429 rate_limit_exceeded
503 service_unavailable - the API is temporarily unavailable
A successful response wraps the payload in the { success, data, timestamp } envelope (also shown live in the panel on the right):
{
"success": true,
"data": {
"request_id": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4_1717000000_4271",
"status": "completed",
"completed": true,
"result": {
"displayname": "Jane Doe",
"firstname": "Jane",
"lastname": "Doe",
"headline": "VP of Product at Acme",
"location": "San Francisco, CA",
"best_business_email": "jane.doe@acme.com",
"best_work_email": "jane.doe@acme.com",
"best_personal_email": "jane@gmail.com",
"altemails": [
"jane.doe@acme.com",
"jane@example.com"
],
"fullphone": [
{
"fullphone": "+1-555-123-4567",
"phone_type": "mobile"
}
],
"social_profiles": {
"linkedin": {
"url": "https://linkedin.com/in/janedoe",
"followers": 2847
},
"twitter": {
"url": "https://x.com/janedoe",
"followers": 1234
}
},
"organizations": [
{
"name": "Acme",
"title": "VP of Product",
"is_current": true
},
{
"name": "StartupXYZ",
"title": "Product Manager",
"is_current": false
}
],
"classifications": {
"seniority": [
"vp"
],
"job_functions": [
"product_management"
],
"employment_types": [
"full_time"
]
},
"total_experience_years": 12
},
"error": null,
"created_on": "2026-01-15T10:34:21",
"completed_on": "2026-01-15T10:35:00"
},
"timestamp": "2026-01-01T00:00:00"
}