docs sourcing
People and contacts
Fetch up to 100 people, match by name and company, cached reads, and contact details.
Person endpoints work on profile_ids from search, runs, and lists, or on public profile URLs. Reading never charges; fetching is a paid call with a dry run.
| Call | What it does | Cost |
|---|---|---|
GET /v1/people/{profile_id} | Your cached copy | Free, always |
POST /v1/people:fetch | Full profiles for up to 100 ids or URLs | 2 credits per live profile found |
POST /v1/people:match | One person by name and current company | 1 credit, only on an exact match |
POST /v1/people/{profile_id}/contacts | Personal email and phone | 25 credit, only when found |
Cached reads
GET /v1/people/{profile_id} never calls the person index and never charges. A person not fetched in this workspace within max_age_days is 404 not_cached; fetch them first. profile_id may also be a URL-encoded profile URL.
Fetch
{ "ids": ["ACwAAA1", "ACwAAA2"], "max_age_days": 30 }
Up to 100 ids and URLs together. Cached copies younger than max_age_days (default 30) are free. enrich_companies: true adds industry and size to each experience entry.
When everything is cached, the profiles come back at once (200). Otherwise a job is queued (202): follow it with GET /v1/jobs/{job_id} or the job.completed event. The result has data (profiles), not_found (ids that do not exist, free), and omitted.suppressed (never fetched, never charged).
The profile is the complete normalized record the index returns: headline, summary, locations, experience with dates, education, skills, languages, certifications, and open_to_work. There is no separate raw upstream record; API layers explains why.
Match
POST /v1/people:match with first_name and last_name (or full_name) and company reads one search page for the name at the company. outcome is exact (one person, 1 credit the first time), ambiguous, or none (both free).
Contacts
Personal email and phone are a sourcing add-on and need the contacts:spend scope. The person must be fetched first.
POST /v1/people/{profile_id}/contacts looks one person up; POST /v1/people/contacts:fetch takes up to 100 profile_ids. Both take ?dry_run=true and need an Idempotency-Key to execute. Answers may arrive later: status is pending until then, and contacts.completed is emitted.
Each email or phone has value, type (personal or work), and confidence. status is ready, not_found, pending, or expired. GET reads what is stored, free. DELETE removes it.
25 credit covers both email and phone when either is found. A miss is free. A suppressed person is refused before any lookup. A second lookup while stored contacts are still valid does not charge.
Erasure and retention
POST /v1/erasures with profile_id, profile_url, or both erases one person from the workspace: cached profiles and search pages, candidates, seen entries, list items, stored contacts, and outreach records. It redacts runs, jobs, and audit metadata. Unless you pass suppress: false, a hashed suppression is kept so the person never comes back. DELETE /v1/people/{profile_id} erases without suppressing. Both are free.
| Data | Kept for |
|---|---|
| Cached profiles and search pages | 30 days, or until DELETE /v1/privacy/cache |
| Stored contacts | 30 days |
| Idempotency and MCP replay rows | 24 hours |
| Events | 30 days. Ids and counts only |
| Credit ledger and audit log | Kept for accounting. No names or profile URLs after an erasure |
Ask Claude
Fetch the full profiles of the five people I starred, then compare their experience with the role. Facts only, no score.
Reference: getPerson, fetchPeople, matchPerson, lookupPersonContacts, and createErasure in the API reference.