> ## Documentation Index
> Fetch the complete documentation index at: https://docs.crustdata.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Person Enrichment
> Enrich person profiles by profile URL — first enrichment, field selection, batch, and the Search-then-Enrich workflow.
The Person Enrich API takes a profile URL and returns a rich person profile.
This page covers the basics (your first enrichment and the response shape)
plus worked example recipes. For the request/response schema and errors, see
[Enrich reference](/person-docs/enrichment/reference).
Every request goes to the same endpoint:
```
POST https://api.crustdata.com/person/enrich
```
Replace `YOUR_API_KEY` in each example with your actual API key. All
requests require the `x-api-version: 2025-11-01` header.
### Request body
| Parameter | Type | Required | Description |
| ----------------------------------- | ----- | -------- | -------------------------------------------------- |
| `professional_network_profile_urls` | array | Yes | Profile URLs to enrich. Max 25 per request. |
| `fields` | array | No | Specific field paths or section groups to include. |
### Response body
The response is a top-level array. Each entry corresponds to one input
identifier.
| Field | Type | Description |
| ---------------------------- | ------ | ----------------------------------------------------------------- |
| `matched_on` | string | The input profile URL |
| `match_type` | string | `professional_network_profile_url` |
| `matches` | array | Candidate matches. Empty for no-match inputs. |
| `matches[].confidence_score` | number | 0 to 1. Higher is better. `1.0` is common for direct URL lookups. |
| `matches[].person_data` | object | Full enriched profile. |
### Rate limits and pricing
Pricing: Base profile is 1 credit. Developer
platform data adds 1 credit. Maximum:
2 credits per profile.
Need email addresses or phone numbers? Use
[Contact Enrich](/person-docs/contact/enrich).
Request parameters, response fields, valid `fields` values,
`person_data` sections, advanced flags, errors.
***
## Your first enrichment: look up a profile
The simplest enrichment takes a single profile URL and returns the person's
cached profile. Pass the URL in the `professional_network_profile_urls`
array.
```bash Request theme={"theme":"vitesse-black"}
curl --request POST \
--url https://api.crustdata.com/person/enrich \
--header 'authorization: Bearer YOUR_API_KEY' \
--header 'content-type: application/json' \
--header 'x-api-version: 2025-11-01' \
--data '{
"professional_network_profile_urls": [
"https://www.linkedin.com/in/abhilashchowdhary/"
]
}'
```
```json Response theme={"theme":"vitesse-black"}
[
{
"matched_on": "https://www.linkedin.com/in/abhilashchowdhary/",
"match_type": "professional_network_profile_url",
"matches": [
{
"confidence_score": 1.0,
"person_data": {
"basic_profile": {
"name": "Abhilash Chowdhary",
"headline": "Co-founder at Crustdata (YC F24) | Real-time B2B data for AI agents",
"current_title": "Co-Founder & CEO",
"summary": "Love building things. A software engineer with vast experience in shipping products spanning robotics, web technologies and quantitative finance.",
"location": {
"city": null,
"continent": null,
"country": null,
"raw": "San Francisco, California, United States",
"state": null
},
"languages": ["English", "Hindi"],
"last_updated": "2026-03-03T17:09:31.949863Z"
},
"crustdata_person_id": 1068035,
"social_handles": {
"twitter_identifier": {}
}
}
}
]
}
]
```
Response trimmed for clarity. The full response can include employment
history, education, skills, and developer platform profiles when available.
### Understanding the response
The Enrich API returns an **array** — one entry per identifier you
submitted. Each entry has three fields:
* **`matched_on`** — the profile URL you submitted.
* **`match_type`** — `professional_network_profile_url`.
* **`matches`** — an array of candidate profiles. Each match includes a `confidence_score` (0 to 1) and the full `person_data` object.
For profile URL lookups, you will typically get exactly one match with a
`confidence_score` of `1.0`, because the URL is a direct identifier.
### Need fresh data from the web?
If the cached enrich response is missing a recent update or you need
real-time retrieval from the web, use
[Person Live Enrich](/person-docs/enrichment/live-enrich). That endpoint is designed for
fresh profile retrieval when cached enrich is not enough.
***
## Examples
Worked recipes you can copy, paste, and adapt.
### Selecting fields: education, employers, and more
By default, `/person/enrich` returns only the `basic_profile` and
`social_handles` sections. Employment history, education, and skills are
**not** returned unless you request them with the `fields` parameter.
Request any of these sections (or dot-paths within them) in `fields`:
| Section | Returns |
| -------------------------- | -------------------------------------------------------------------------------------------------------- |
| `experience` | Employment history — current and past roles, each with company, `crustdata_company_id`, title, and dates |
| `education` | Schools, degrees, and fields of study |
| `skills` | Professional skills |
| `professional_network` | Connections, followers, and profile metadata |
| `dev_platform_profiles` | Developer platform context (extra credit) |
| `certifications`, `honors` | Certifications and awards (gated — require field-level permission on your key) |
`experience`, `education`, `skills`, and `professional_network` are part of
the base profile (**1 credit**) — requesting them adds **no extra credits**.
`dev_platform_profiles` costs more. See [Pricing](/general/pricing) and the full
[field catalog](/person-docs/enrichment/reference#person_data-sections).
Pass `experience` to get each role's company, `crustdata_company_id`, title, and dates.
```bash Request theme={"theme":"vitesse-black"}
curl --request POST \
--url https://api.crustdata.com/person/enrich \
--header 'authorization: Bearer YOUR_API_KEY' \
--header 'content-type: application/json' \
--header 'x-api-version: 2025-11-01' \
--data '{
"professional_network_profile_urls": ["https://www.linkedin.com/in/dvdhsu/"],
"fields": ["basic_profile", "experience"]
}'
```
```json Response theme={"theme":"vitesse-black"}
[
{
"matched_on": "https://www.linkedin.com/in/dvdhsu/",
"match_type": "professional_network_profile_url",
"matches": [
{
"confidence_score": 1.0,
"person_data": {
"basic_profile": { "name": "David Hsu", "current_title": "Founder, CEO" },
"experience": {
"employment_details": {
"current": [
{
"name": "Retool",
"title": "Founder, CEO",
"crustdata_company_id": 633593,
"start_date": "2017-01-01T00:00:00+00:00"
}
],
"past": []
}
}
}
}
]
}
]
```
Pass `education` for each school, degree, and field of study.
```bash Request theme={"theme":"vitesse-black"}
curl --request POST \
--url https://api.crustdata.com/person/enrich \
--header 'authorization: Bearer YOUR_API_KEY' \
--header 'content-type: application/json' \
--header 'x-api-version: 2025-11-01' \
--data '{
"professional_network_profile_urls": ["https://www.linkedin.com/in/dvdhsu/"],
"fields": ["basic_profile", "education"]
}'
```
```json Response (trimmed to the education section) theme={"theme":"vitesse-black"}
{
"education": {
"schools": [
{
"school": "University of Oxford",
"degree": "Bachelor of Arts (B.A.)",
"field_of_study": "Philosophy and Computer Science"
}
]
}
}
```
Name every section you want in one call. `experience`, `education`, `skills`,
and `professional_network` are part of the base profile (no extra credits).
`dev_platform_profiles` adds a credit. `certifications` and `honors` are
omitted here — they require field-level permission on your key and otherwise
return an error (see the gated example below).
```bash Request theme={"theme":"vitesse-black"}
curl --request POST \
--url https://api.crustdata.com/person/enrich \
--header 'authorization: Bearer YOUR_API_KEY' \
--header 'content-type: application/json' \
--header 'x-api-version: 2025-11-01' \
--data '{
"professional_network_profile_urls": ["https://www.linkedin.com/in/dvdhsu/"],
"fields": [
"basic_profile",
"professional_network",
"experience",
"education",
"skills",
"social_handles",
"dev_platform_profiles"
]
}'
```
```json Response (trimmed) theme={"theme":"vitesse-black"}
{
"basic_profile": { "name": "David Hsu", "current_title": "Founder, CEO" },
"professional_network": { "connections": 700, "followers": 14319, "joined_date": "2007-12-01T00:00:00+00:00", "open_to_cards": [] },
"experience": {
"employment_details": {
"current": [
{ "name": "Retool", "title": "Founder, CEO", "crustdata_company_id": 633593 }
],
"past": []
}
},
"education": {
"schools": [
{ "school": "University of Oxford", "degree": "Bachelor of Arts (B.A.)", "field_of_study": "Philosophy and Computer Science" }
]
},
"skills": { "professional_network_skills": [] },
"social_handles": {
"professional_network_identifier": { "profile_url": "https://www.linkedin.com/in/dvdhsu" }
},
"dev_platform_profiles": []
}
```
To also include `certifications` and `honors`, your API key needs
field-level permission — contact Crustdata to enable them. `skills` and
`dev_platform_profiles` may be empty for some profiles.
Use dot-paths to pull just the sub-fields you need instead of whole sections.
```bash theme={"theme":"vitesse-black"}
curl --request POST \
--url https://api.crustdata.com/person/enrich \
--header 'authorization: Bearer YOUR_API_KEY' \
--header 'content-type: application/json' \
--header 'x-api-version: 2025-11-01' \
--data '{
"professional_network_profile_urls": ["https://www.linkedin.com/in/dvdhsu/"],
"fields": ["basic_profile.name", "experience.employment_details.current.title", "education.schools.degree"]
}'
```
Request the `social_handles` section to get the person's canonical profile
URLs — useful for keying records or linking out to the profile.
```bash Request theme={"theme":"vitesse-black"}
curl --request POST \
--url https://api.crustdata.com/person/enrich \
--header 'authorization: Bearer YOUR_API_KEY' \
--header 'content-type: application/json' \
--header 'x-api-version: 2025-11-01' \
--data '{
"professional_network_profile_urls": ["https://www.linkedin.com/in/dvdhsu/"],
"fields": ["basic_profile.name", "social_handles"]
}'
```
```json Response theme={"theme":"vitesse-black"}
[
{
"matched_on": "https://www.linkedin.com/in/dvdhsu/",
"match_type": "professional_network_profile_url",
"matches": [
{
"confidence_score": 1.0,
"person_data": {
"basic_profile": { "name": "David Hsu" },
"social_handles": {
"professional_network_identifier": {
"profile_url": "https://www.linkedin.com/in/dvdhsu",
"urn_url": "https://www.linkedin.com/in/ACoAAAEnBBoBUwCVyafB-XsEBTeHaFN8ScMKh6U"
},
"dev_platform_identifier": { "profile_url": null },
"twitter_identifier": { "slug": "" }
}
}
}
]
}
]
```
* **`profile_url`** — the canonical vanity URL. The slug can change if the
person edits it.
* **`urn_url`** — the permanent URN-based URL, which never changes. Use it (or
`crustdata_person_id`) as a stable per-person key.
`urn_url` requires **field-level permission** on your API key and is absent
from the response by default — contact support to enable it. Both URL forms
are accepted as input identifiers in `professional_network_profile_urls`.
Set `preview: true` to get a lightweight response at **0 credits**: the
`crustdata_person_id`, `basic_profile`, `social_handles.professional_network_identifier`,
and the person's connection count and profile picture. Any `fields` you pass are
ignored in preview mode, and `preview` cannot be combined with `enrich_realtime`.
```bash Request theme={"theme":"vitesse-black"}
curl --request POST \
--url https://api.crustdata.com/person/enrich \
--header 'authorization: Bearer YOUR_API_KEY' \
--header 'content-type: application/json' \
--header 'x-api-version: 2025-11-01' \
--data '{
"professional_network_profile_urls": ["https://www.linkedin.com/in/dvdhsu/"],
"preview": true
}'
```
Preview is **enterprise only** and must be enabled for your account —
contact the Crustdata team to turn it on. Without it, the API returns
`400 invalid_request` with the message `Preview feature is not available
for your account. Please reach out to Crustdata team.`
`dev_platform_profiles` returns developer platform context (repos, orgs,
activity) and adds **+1** credit.
```bash theme={"theme":"vitesse-black"}
curl --request POST \
--url https://api.crustdata.com/person/enrich \
--header 'authorization: Bearer YOUR_API_KEY' \
--header 'content-type: application/json' \
--header 'x-api-version: 2025-11-01' \
--data '{
"professional_network_profile_urls": ["https://www.linkedin.com/in/dvdhsu/"],
"fields": ["basic_profile", "dev_platform_profiles"]
}'
```
Starting **from** a dev-platform URL instead? `/person/enrich` does not
accept dev-platform URLs as identifiers (the legacy endpoint did). Use the
[Dev Platform API](/person-docs/dev_platform/introduction) —
`POST /dev_platform/enrich` takes `profile_url:
"https://github.com/"` or a `crustdata_person_id` directly.
`certifications` and `honors` require field-level permission on your API key.
Without it, the request returns a permission error — contact Crustdata to enable
them for your key.
```bash theme={"theme":"vitesse-black"}
curl --request POST \
--url https://api.crustdata.com/person/enrich \
--header 'authorization: Bearer YOUR_API_KEY' \
--header 'content-type: application/json' \
--header 'x-api-version: 2025-11-01' \
--data '{
"professional_network_profile_urls": ["https://www.linkedin.com/in/dvdhsu/"],
"fields": ["basic_profile", "certifications", "honors"]
}'
```
### More recipes
Not every identifier will resolve to a person. When there is no match, the
`matches` array is empty.
```bash Request theme={"theme":"vitesse-black"}
curl --request POST \
--url https://api.crustdata.com/person/enrich \
--header 'authorization: Bearer YOUR_API_KEY' \
--header 'content-type: application/json' \
--header 'x-api-version: 2025-11-01' \
--data '{
"professional_network_profile_urls": [
"https://www.linkedin.com/in/no-such-profile/"
]
}'
```
```json Response theme={"theme":"vitesse-black"}
[
{
"matched_on": "https://www.linkedin.com/in/no-such-profile/",
"match_type": "professional_network_profile_url",
"matches": []
}
]
```
You still get a response entry for the identifier — `matched_on` tells you
which input had no match. This makes it easy to track which lookups
succeeded and which need a different approach.
You can enrich up to **25 identifiers** in a single request. The response
returns one entry per identifier, in the same order you submitted them.
```bash Request theme={"theme":"vitesse-black"}
curl --request POST \
--url https://api.crustdata.com/person/enrich \
--header 'authorization: Bearer YOUR_API_KEY' \
--header 'content-type: application/json' \
--header 'x-api-version: 2025-11-01' \
--data '{
"professional_network_profile_urls": [
"https://www.linkedin.com/in/dvdhsu/",
"https://www.linkedin.com/in/abhilashchowdhary/"
]
}'
```
```json Response theme={"theme":"vitesse-black"}
[
{
"matched_on": "https://www.linkedin.com/in/dvdhsu/",
"match_type": "professional_network_profile_url",
"matches": [
{
"confidence_score": 1.0,
"person_data": {
"basic_profile": {
"name": "David Hsu",
"headline": "Founder, CEO @ Retool",
"current_title": "Founder, CEO",
"location": {
"city": "San Francisco",
"state": "California",
"country": "United States",
"continent": "North America",
"raw": "San Francisco Bay Area"
}
},
"social_handles": {
"professional_network_identifier": {
"profile_url": "https://www.linkedin.com/in/dvdhsu"
}
}
}
}
]
},
{
"matched_on": "https://www.linkedin.com/in/abhilashchowdhary/",
"match_type": "professional_network_profile_url",
"matches": [
{
"confidence_score": 1.0,
"person_data": {
"basic_profile": {
"name": "Abhilash Chowdhary",
"headline": "Co-founder at Crustdata (YC F24) | Real-time B2B data for AI agents",
"current_title": "Co-Founder & CEO",
"location": {
"city": "San Francisco",
"state": "California",
"country": "United States of America",
"continent": "North America",
"raw": "San Francisco, California, United States"
}
},
"social_handles": {
"professional_network_identifier": {
"profile_url": "https://www.linkedin.com/in/abhilashchowdhary"
}
}
}
}
]
}
]
```
Response trimmed for clarity.
**Batch enrichment tips**
* The maximum batch size is **25 identifiers** per request.
* Each entry in the response corresponds to the input at the same position, so you can match results back to your input list by index.
* If some identifiers fail to match, their `matches` array will be empty, but the request still succeeds for the others.
The most powerful pattern combines [Person Search](/person-docs/search/introduction) with
Person Enrich. Search finds people matching your criteria; Enrich gets the
full profile for each match.
**Step 1:** Search for decision-makers at a target company.
```bash theme={"theme":"vitesse-black"}
curl --request POST \
--url https://api.crustdata.com/person/search \
--header 'authorization: Bearer YOUR_API_KEY' \
--header 'content-type: application/json' \
--header 'x-api-version: 2025-11-01' \
--data '{
"filters": {
"op": "and",
"conditions": [
{
"field": "experience.employment_details.current.company_name",
"type": "in",
"value": ["Retool"]
},
{
"field": "experience.employment_details.current.title",
"type": "(.)",
"value": "VP|Director|Head of"
}
]
},
"limit": 5
}'
```
**Step 2:** Take the profile URLs from the search results and enrich them
for full profiles.
```bash theme={"theme":"vitesse-black"}
curl --request POST \
--url https://api.crustdata.com/person/enrich \
--header 'authorization: Bearer YOUR_API_KEY' \
--header 'content-type: application/json' \
--header 'x-api-version: 2025-11-01' \
--data '{
"professional_network_profile_urls": [
"https://www.linkedin.com/in/dvdhsu/",
"https://www.linkedin.com/in/abhilashchowdhary/"
]
}'
```
This two-step pattern is the foundation for most sales, recruiting, and
research workflows. Search narrows the universe; Enrich fills in the
details.
***
## What to do next
* **Look up request/response details** — see [Enrich reference](/person-docs/enrichment/reference) for parameters, valid `fields` values, `person_data` sections, and errors.
* **Search first, then enrich** — use [Person Search](/person-docs/search/introduction) to find people by name, title, company, or location, then enrich the results.
* **Fetch fresh data from the web** — use [Person Live Enrich](/person-docs/enrichment/live-enrich) when cached enrich is not enough.