---
title: "Person Enrichment API Reference | Leadsets Docs"
description: "POST /v1/people/enrich: current role, company and best work email from a LinkedIn URL, email or name and domain. 1 record when found, 0 when not."
canonical: https://www.leadsets.ai/docs/api/people-enrich
updated: 2026-11-11
---

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/enrich MCP: 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_url string

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

email string

A known work email.

full_name string

Full name. Use with `company_domain`.

first_name string

Instead of `full_name`, with `last_name` and `company_domain`.

last_name string

Instead of `full_name`, with `first_name` and `company_domain`.

company_domain string

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

include_personal_email boolean

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

prompt string

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](https://www.leadsets.ai/docs/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_companies**](https://www.leadsets.ai/docs/api/companies-search) [Next
**enrich_company →**](https://www.leadsets.ai/docs/api/companies-enrich)

Was this page useful? [Tell us](mailto:support@leadsets.ai?subject=Docs%20feedback%3A%20%2Fdocs%2Fapi%2Fpeople-enrich)

```bash
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
 }'
```

```ts
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,
});
```

```python
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,
)
```

Response 200 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"
}
```

---

Leadsets by Mobylogix LLC, 10160 hwy 242, Conroe, TX, 77385, US. Facts for AI assistants: https://www.leadsets.ai/llm · Site index: https://www.leadsets.ai/llms.txt · Every page: https://www.leadsets.ai/llms-full.txt