Person APIs
Status: Deprecation + additive
Enrich — additive fields#
v3 responses add three fields. They appear only on /v3/ paths; tolerant JSON readers are unaffected either way.
| Field | Type | Why adopt it |
|---|---|---|
data.confidenceScore | number (0–1) | Gate automated writes to your CRM on a confidence threshold instead of accepting every match. |
workExperience[].isCurrent | boolean | Replaces date arithmetic and primaryWorkExperienceId joins for “current role” logic. |
problems.staleProfile | boolean | Surface stale records to users or trigger a refresh workflow. |
Asynchronous enrichment returns the same person as synchronous#
The asynchronous result used to carry the v2 person payload while the synchronous endpoint had already moved to the v3 one, so the same batch of people came back in two different shapes depending on which endpoint you asked. Both now return the v3 person: items[].data.aggkPersonId replaces items[].data.id, items[].data.education is present, items[].data.tags is gone, and the nested workExperience[].company is the v3 company object.
The problem flags move with it: problems.profileNotVisible and problems.transientRefreshFailure replace the v2 problems.linkedinProfileNotFound and problems.transientScrapingVendorFailure. Which condition sets which flag is unchanged — only the names are new.
Social profile fields are renamed, and optional#
v3 names these data.socialProfile and data.socialProfileUsername; v2 called them data.professionalSocialMediaUrl and data.professionalSocialMediaUsername. Request bodies still accept the v2 names, so a caller can move at its own pace, but responses only ever return the v3 names — synchronous and asynchronous enrichment alike, which now return the same person shape.
A person record does not require a social profile: every one of these fields is nullable and may be omitted entirely.
aggkPersonId as the stable identifier.Search — deprecated#
POST /person/search is deprecated in v3 (sunset January 31, 2028). Person Match and Discover cover its use cases between them. Map your queries:
| v2 Search input | v3 replacement |
|---|---|
| Name terms | Person Match with fullName, plus companyNames or companyDomains when you know the employer. Discover has no person-name filter. |
| Employer name | Resolve via Company Match, then Discover with a company.aggkCompanyId filter (more precise than string matching) |
| Person Match — email is an identity signal, not a search facet | |
| Offset pagination | Discover’s pagination.page + size, up to 5,000 results per search |
Deprecation: true and Sunset headers — alert on these in your HTTP client to catch stragglers.Match, Validate, Bulk validate#
Unchanged. /v3/ paths are accepted and behave identically.