> ## 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 Enrich reference
> Reference for Person Enrich: request parameters, response fields, fields parameter, person_data sections, and errors.
Reference material for [Person Enrich](/person-docs/enrichment/introduction): request
parameters, response fields, valid `fields` values, `person_data` section
catalog, and errors.
For walk-through examples, see [Person Enrich](/person-docs/enrichment/introduction) and
[Examples](/person-docs/enrichment/examples).
***
## Request parameter reference
| Parameter | Type | Required | Default | Description |
| ----------------------------------- | ------------ | --------------------------------------------------------------- | --------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `professional_network_profile_urls` | string\[] | One of `professional_network_profile_urls` or `business_emails` | — | Profile URLs to enrich. Max 25. |
| `business_emails` | string\[] | One of `professional_network_profile_urls` or `business_emails` | — | Business emails for reverse lookup. Max 25. |
| `fields` | string\[] | No | `basic_profile`, `social_handles` | Specific field paths or section groups to return. When omitted, only `basic_profile` and `social_handles` are returned. |
| `min_similarity_score` | number (0–1) | No | None | Minimum confidence threshold for email reverse lookup matches. |
***
## Response fields reference
Each item in the response array contains:
| Field | Type | Description |
| ---------------------------- | ------ | --------------------------------------------------------------------------------- |
| `matched_on` | string | The input identifier (profile URL or email) |
| `match_type` | string | `professional_network_profile_url` or `business_email` |
| `matches` | array | Array of candidate matches (may be empty for no-match) |
| `matches[].confidence_score` | number | 0 to 1. How confident the match is. `1.0` = exact match. |
| `matches[].person_data` | object | Full enriched profile. See [`person_data` sections](#person_data-sections) below. |
***
## Using the `fields` parameter
By default, the API returns only the `basic_profile` and `social_handles`
sections. Use the `fields` parameter to request the additional sections or
dot-paths you need.
```bash Request — specific fields 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.summary",
"contact",
"dev_platform_profiles"
]
}'
```
### Popular fields for contact and developer workflows
| Field path | What it returns |
| ---------------------------------------------------- | ------------------------------------------------------------------------------ |
| `basic_profile.summary` | The person's summary or about text |
| `contact` | Contact section with email records, phone numbers, and websites when available |
| `contact.business_emails` | Business email records when available |
| `contact.personal_emails` | Personal email records when available |
| `contact.phone_numbers` | Phone numbers when available |
| `contact.websites` | Personal or company-linked websites |
| `dev_platform_profiles` | Developer platform profiles when available |
| `social_handles.dev_platform_identifier.profile_url` | Canonical developer platform profile URL when available |
| `experience.employment_details.current.name` | The person's current company name |
Use `contact` when you want contact-ready records and
`dev_platform_profiles` when you want developer platform context in
the same enrich response.
### `person_data` sections
The `person_data` object contains the following sections. Pass any of these
names to `fields` to include that section, or use dot-paths like
`basic_profile.summary` to request a specific sub-field.
| Section | Key fields | Description |
| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
| `crustdata_person_id` | integer | Top-level Crustdata identifier for the enriched profile |
| `updated_at` | date-time string (nullable) | Top-level timestamp of the most recent profile refresh |
| `basic_profile` | `name`, `first_name`, `last_name`, `headline`, `current_title`, `normalized_title` ([JTN](/guides/job-title-normalization), beta), `professional_network_name`, `summary`, `location`, `languages`, `last_updated`, `profile_picture_permalink` | Core identity and role |
| `professional_network` | `profile_picture_permalink`, `connections`, `followers`, `open_to_cards`, `pronoun`, `location.raw`, `location.city`, `location.state`, `location.country`, `location.continent` | Profile metadata when available |
| `social_handles` | `professional_network_identifier.profile_url`, `dev_platform_identifier.profile_url`, `twitter_identifier.slug` | Available social identifiers |
| `experience` | `employment_details.current[]`, `employment_details.past[]` | Full employment history |
| `education` | `schools[]` | Education background |
| `certifications` | `name`, `issuing_organization`, `issue_date`, `expiration_date` | Certifications. Requires field-level permission on your API key. |
| `honors` | `title`, `issuer`, `issued_date`, `description` | Honors and awards. Requires field-level permission on your API key. |
| `skills` | `professional_network_skills[]` | Professional skills |
| `contact` | `business_emails[]`, `personal_emails[]`, `phone_numbers[]`, `websites[]` | Contact data such as websites, phones, or email records |
| `dev_platform_profiles` | developer platform profile objects | Developer platform data when available |
***
## Fresh data and realtime enrichment
`/person/enrich` serves data from the cached dataset. When you need fresh
profile data retrieved in real time, use the dedicated
[Person Live Enrich](/person-docs/enrichment/live-enrich) endpoint
(`POST /person/professional_network/enrich/live`), which is designed for
real-time retrieval from the web.
If cached enrich is not enough, use
[Person Live Enrich](/person-docs/enrichment/live-enrich) — it is
designed for fresh profile retrieval from the web.
***
## Errors
| Status | Meaning |
| ------ | ---------------------------------------------------------------------- |
| `400` | Invalid request — missing or wrong identifier type, or malformed body. |
| `401` | Invalid or missing API key. |
| `403` | Permission denied or insufficient credits. |
| `500` | Internal server error. |
```json 400 — Bad request theme={"theme":"vitesse-black"}
{
"error": {
"type": "invalid_request",
"message": "Exactly one identifier type must be provided.",
"metadata": []
}
}
```
```json 401 — Invalid API key theme={"theme":"vitesse-black"}
{
"error": {
"type": "unauthorized",
"message": "Invalid API key in request.",
"metadata": []
}
}
```
***
## API reference summary
| Detail | Value |
| ------------ | --------------------------------------------------------------------------------------------------------------------- |
| **Endpoint** | `POST /person/enrich` |
| **Auth** | Bearer token + `x-api-version: 2025-11-01` |
| **Request** | One of `professional_network_profile_urls` or `business_emails` (max 25). Optional: `fields`, `min_similarity_score`. |
| **Response** | Top-level array: `[{ matched_on, match_type, matches: [{ confidence_score, person_data }] }]` |
| **No match** | `200` with empty `matches: []` for unmatched identifiers. |
| **Errors** | `400` (bad request), `401` (bad auth), `403` (permission/credits), `500` (server error) |
See the [full API reference](/openapi-specs/2025-11-01/introduction) for
the complete OpenAPI schema.