The Person APIs help you answer practical questions about people: Who are the decision-makers at a target company? What does this person’s professional background look like? Can I find people by name, title, location, or employer? Can I resolve a person from a LinkedIn URL or business email?
There are four core endpoints, each designed for a different step in your workflow.
| API | What it does | Best for |
|---|
| Search | Find people matching structured filters | Prospecting, talent sourcing, market mapping |
| Enrich | Get a detailed profile from a LinkedIn URL or email | Outreach prep, due diligence, profile building |
| Identify | Resolve a person from a LinkedIn URL or email (lightweight) | CRM deduplication, lead routing, entity resolution |
| Autocomplete | Discover valid field values for search filters | Building filter dropdowns, validating filter inputs |
At a glance
| Search | Autocomplete | Enrich | Identify |
|---|
| Endpoint | /person/search | /person/search/autocomplete | /person/enrich | /person/identify |
| Data source | Crustdata indexed | Crustdata indexed | Crustdata indexed | Crustdata indexed |
| Purpose | Find people by filters | Discover valid filter values | Get full person profile | Match partial info to a person |
| Filter syntax | { "field": "dotpath", "type": "op", "value": ... } | Optional filters param | N/A | N/A |
| Pagination | Cursor-based | — | — | — |
| Field selection | fields = dot-paths | — | fields = dot-paths or section groups | fields = dot-paths or section groups |
| Error codes | 400, 401, 403, 500 | 400, 401, 500 | 400, 401, 403, 404, 500 | 400, 401, 403, 404, 500 |
Before you start
You need:
- A Crustdata API key
- A terminal with
curl (or any HTTP client)
- The required header:
x-api-version: 2025-11-01
All requests use Bearer token authentication and require the API version header:
--header 'authorization: Bearer YOUR_API_KEY'
--header 'x-api-version: 2025-11-01'
Replace YOUR_API_KEY in each example with your actual API key.
Convention used in these docs: Information labeled “OpenAPI contract”
reflects the formal API specification. Information labeled “Current platform
behavior” (such as rate limits, credit costs, and max page ranges) describes
observed behavior that may change. See the API reference
for the formal OpenAPI spec.
Quickstart: enrich a person from a LinkedIn URL
The fastest way to get started is to enrich a person from their LinkedIn profile URL. This single request returns the full person profile from the Crustdata cache.
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"
]
}'
Response trimmed for clarity. The full response includes employment history,
education, skills, contact information, and more.
matched_on — the input you sent (https://www.linkedin.com/in/abhilashchowdhary).match_type — which identifier type was used (professional_network_profile_url or business_email).confidence_score — how confident the match is (1.0 = exact match).person_data — the full person profile, including basic_profile, experience, education, skills, social_handles, and more.
Which API should you start with?
| If you want to… | Start with |
|---|
| Find people by name, title, company, or location | Search |
| Get full profile details for a known LinkedIn URL | Enrich |
| Reverse-lookup a person from a business email | Enrich |
| Quickly resolve a person without full enrichment | Identify |
| Discover valid filter values before building search queries | Autocomplete |
| Build a list of decision-makers at target companies | Search |
Common workflows
- Discovery — Start with Autocomplete to find valid filter values (e.g., title variations), then Search to build your list, then Enrich the top matches for full profiles.
- Data cleanup — Use Enrich with
business_emails to reverse-lookup LinkedIn profiles and fill in missing professional context from CRM imports.
- Lead routing — Enrich incoming LinkedIn URLs to get a stable person profile, then Search for similar people at the same company or with the same title.
Error handling
All Person API endpoints return structured errors. The exact status codes vary by endpoint:
| Status | Meaning | Applies to |
|---|
400 | Invalid request (bad field, wrong operator, malformed filters) | All endpoints |
401 | Invalid or missing API key | All endpoints |
403 | Permission denied or insufficient credits | Search, Enrich, Identify |
404 | No data found (per spec) | Enrich, Identify |
500 | Internal server error | All endpoints |
{
"error": {
"type": "invalid_request",
"message": "Unsupported filter field: 'current_title'. Supported fields: ['basic_profile.name', 'basic_profile.headline', ...]",
"metadata": []
}
}
401, the format is simpler: {"message": "Invalid API key in request"}.
No-match behavior
| Endpoint | No matches found | Action |
|---|
| Search | 200 with empty profiles: [] | Broaden filters or check with Autocomplete |
| Enrich | 200 with empty matches: [] | Try a different identifier type |
| Identify | 200 with empty matches: [] | Try a different identifier |
| Autocomplete | 200 with empty suggestions: [] | Try a broader query |
The OpenAPI spec defines 404 for Enrich and Identify, but current behavior
typically returns 200 with empty matches. Handle both.
Retry guidance
| Status | Retry? | Action |
|---|
400 | No | Fix the request |
401 | No | Check API key |
403 | No | Check permissions/credits |
404 | No | Try different identifier |
500 | Yes | Exponential backoff (1s, 2s, 4s) |
Terminology reference
These are the most common terms used across the Person APIs:
| You say | API request field | Used in |
|---|
| LinkedIn profile URL | professional_network_profile_urls | Enrich, Identify |
| Business email | business_emails | Enrich, Identify |
| Person name | basic_profile.name (filter field) | Search, Autocomplete |
| Job title | experience.employment_details.current.title (filter field) | Search, Autocomplete |
| Current company | experience.employment_details.current.company_name (filter field) | Search, Autocomplete |
| Headline | basic_profile.headline (filter field) | Search, Autocomplete |
| Location | basic_profile.location (filter field) | Search |
Search uses dot-path field names like
experience.employment_details.current.title. Use Autocomplete to discover
exact values for indexed Search filters before you build queries.
| Mistake | Fix |
|---|
Using linkedin_profile_urls in Enrich | The correct field is professional_network_profile_urls. |
Using column in Search filters | The correct key is field (e.g., "field": "basic_profile.name"). |
| Mixing identifier types in Enrich | Send one type per request: either professional_network_profile_urls or business_emails. |
Using current_title as a filter field in Search | Use the full dot-path: experience.employment_details.current.title. |
Omitting fields in Search | Returns all fields per person — very large payloads. Always specify fields in production. |
Expecting results wrapper in Enrich response | Enrich returns a top-level array, not { "results": [...] }. Identify wraps in { "results": [...] }. |
Next steps
- Person Search — find people by name, title, company, location, and more with advanced filters.
- Person Autocomplete — discover valid filter values before building queries.
- Person Enrich — get detailed profiles from LinkedIn URLs or business emails, with batch support.
- Person Identify — resolve partial person info to a known entity.
- Person Examples — ready-to-copy workflow patterns.
