REST API / People

Enrich a person

A person's current role, company and best work email, with its status and when it was checked. Look them up by LinkedIn URL, work email, or name plus company domain.

POST/v1/people/enrichMCP: enrich_person

Records

1 when found, +1 for a personal email

Meters

enrichment records + requests / 5 hrs, records / week

Not found

0 records · 1 request

Body parameters

linkedin_urlstring

A linkedin.com/in/… profile URL. The strongest identifier.

emailstring

A known work email.

full_namestring

Full name. Use with company_domain.

first_namestring

Instead of full_name, with last_name and company_domain.

last_namestring

Instead of full_name, with first_name and company_domain.

company_domainstring

The company's domain, e.g. "northwind.io". Needed with a name.

include_personal_emailboolean

Also return a personal email (US) when there is one. One more enrichment record when it comes back.

promptstring

Optional. The request in plain language, up to 1,000 characters. Stored with the call in your request log.

Send one identifier: linkedin_url, email, or a name with company_domain. If you send several, linkedin_url wins, then email. matched_by in the response says which one was used.

Response

person with person_id, full_name, first_name, last_name, title, seniority and function (plus the finer seniority_detail and function_detail), linkedin_url, location, company, email (address, status, type, confidence, checked_at), personal_email when you asked for one, freshness (refreshed_at, confirmed_at, stale_after_at, stale) and sources, which gives the last-seen date and confidence of every returned field. Then matched_by, usage and request_id.

An email is labelled verified only when it was verified. Invalid, suppressed and outdated emails (from before a job change) are never returned, so email can be null.

Personal emails have their own cap on Team and Max. Up to 75,000 a week. At the cap, or when the window has only one record left, the person still comes back without the personal email, with personal_email_note saying why.

Errors

Status	type	Meaning
`400`	`invalid_request`	A value isn't valid. The message names the field in `param`.
`401`	`unauthorized`	Missing, invalid, expired or revoked key. See Authentication.
`402`	`free_records_exhausted`	Free plan: the 1,000 free enrichment records or the 1,000 free data calls are used up.
`403`	`forbidden`	The key is read only. Data tools need a key with data access.
`404`	`not_found`	No match for that input. Nothing was counted.
`429`	`window_full`	A five-hour records or requests window is full. See Retry-After and `resets_at`.
`429`	`weekly_limit`	The seven-day records limit is reached. Resume after `resets_at`.

Previous
← search_companiesNext
enrich_company →

Was this page useful? Tell us

cURLTypeScriptPython

curl https://api.leadsets.ai/v1/people/enrich \
  -H "Authorization: Bearer $LEADSETS_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 9e4a…" \
  -d '{
    "linkedin_url": "https://www.linkedin.com/in/mayachen",
    "include_personal_email": true
  }'

import { Leadsets } from "@leadsetsai/sdk";

const ls = new Leadsets(process.env.LEADSETS_KEY);
const res = await ls.people.enrich({
  linkedin_url: "https://www.linkedin.com/in/mayachen",
  include_personal_email: true,
});

import os
from leadsets import Leadsets

ls = Leadsets(os.environ["LEADSETS_KEY"])
res = ls.people.enrich(
    linkedin_url="https://www.linkedin.com/in/mayachen",
    include_personal_email=True,
)

Response200 OK

{
  "person": {
    "person_id": "6f1c2a9e-3b7d-4e1f-9a52-8c0d4b6e7f13",
    "full_name": "Maya Chen", "first_name": "Maya", "last_name": "Chen",
    "title": "VP Sales", "seniority": "vp", "function": "revenue",
    "linkedin_url": "https://www.linkedin.com/in/mayachen",
    "location": { "country": "US", "region": "CA", "city": "San Francisco" },
    "company": { "name": "Northwind Analytics", "domain": "northwind.io",
                 "employees": 120, "employee_range": "51-200" },
    "email": { "address": "maya@northwind.io", "status": "verified",
               "type": "business", "confidence": 0.95,
               "checked_at": "2026-11-02T00:00:00Z" },
    "personal_email": { "address": "maya.chen.sf@gmail.com",
                        "status": "verified", "type": "personal" },
    "refreshed_at": "2026-11-01T00:00:00Z", "stale": false
  },
  "matched_by": "linkedin_url",
  "usage": { "enrich_records_counted": 2, "enrich_records_left_5h": 14998,
             "enrich_requests_left_5h": 74999, "enrich_records_left_week": 74998 },
  "request_id": "req_7a20c4e91b3f"
}