> ## 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.
# Enrich People
> Enrich person records using the Crustdata cached dataset. Provide either a profile URL or a business email
to retrieve detailed person data including employment history, education, skills, contact information, and developer platform data when available.
Exactly one identifier type must be provided per request. Supports batch enrichment of up to 25 profiles at once.
Default `rate-limit` is 15 requests per minute. Send an email to [gtm@crustdata.co](mailto:gtm@crustdata.co) to discuss higher limits if needed for your use case.
## OpenAPI
````yaml /openapi-specs/2025-11-01/person.yaml post /person/enrich
openapi: 3.0.3
info:
title: Person Dataset API
version: '2025-11-01'
description: >
The Person Dataset API provides a comprehensive suite of endpoints for
discovering, enriching, and managing person data at scale.
- **Search**: Query the person database using flexible filters, sorting, and
pagination to find people matching specific criteria such as job title,
company, location, and more.
- **Enrich**: Enrich person records from the cached dataset using profile
URLs or business emails, returning detailed professional and contact
information.
- **Live Enrich**: Fetch fresh profile data from the web when a profile is
not yet in the cache or when the latest data is needed.
- **Autocomplete**: Get type-ahead suggestions for person search fields,
useful for building search UIs with field value previews.
- **Realtime Search**: Search people in real time using live person search
filters, supporting both synchronous and asynchronous (background job)
modes.
servers:
- url: https://api.crustdata.com
description: Production API server
security:
- bearerAuth: []
tags:
- name: Person APIs
description: Core person data operations
- name: Search APIs
description: Endpoints for searching and discovering people
- name: Enrich APIs
description: Endpoints for enriching person records
- name: Autocomplete APIs
description: Endpoints for field value autocomplete suggestions
paths:
/person/enrich:
post:
tags:
- Person APIs
- Enrich APIs
summary: Enrich person profiles from cached dataset
description: >
Enrich person records using the Crustdata cached dataset. Provide either
a profile URL or a business email
to retrieve detailed person data including employment history,
education, skills, contact information, and developer platform data when
available.
Exactly one identifier type must be provided per request. Supports batch
enrichment of up to 25 profiles at once.
Default `rate-limit` is 15 requests per minute. Send an email to [gtm@crustdata.co](mailto:gtm@crustdata.co) to discuss higher limits if needed for your use case.
operationId: enrichPersonDataset
parameters:
- $ref: '#/components/parameters/ApiVersion'
requestBody:
required: true
description: >-
Person identifier (profile URL or business email) and optional field
selection.
content:
application/json:
schema:
$ref: '#/components/schemas/PersonEnrichRequest'
examples:
enrich_by_profile_url:
summary: Enrich by profile URL
value:
professional_network_profile_urls:
- https://www.linkedin.com/in/abhilashchowdhary
enrich_by_email:
summary: Enrich by business email
value:
business_emails:
- abhilash@crustdata.com
responses:
'200':
description: Enriched person profiles
content:
application/json:
schema:
$ref: '#/components/schemas/PersonEnrichResponse'
examples:
enrich_by_profile_url_response:
summary: Enrichment result for profile URL
value:
- matched_on: https://www.linkedin.com/in/abhilashchowdhary
match_type: professional_network_profile_url
matches:
- confidence_score: 1
person_data:
basic_profile:
current_title: Co-Founder & CEO
headline: Co-founder at Crustdata (YC F24)
name: Abhilash Chowdhary
location:
raw: San Francisco, California, United States
enrich_by_email_response:
summary: Enrichment result for business email
value:
- matched_on: abhilash@crustdata.com
match_type: business_email
matches:
- confidence_score: 1
person_data:
basic_profile:
current_title: Co-Founder & CEO
name: Abhilash Chowdhary
'400':
description: Invalid request parameters
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
missing_identifier:
summary: Missing required identifier
value:
error:
type: invalid_request
message: >-
Exactly one identifier must be provided:
professional_network_profile_urls or business_emails
metadata: []
both_identifiers:
summary: Both identifier types supplied
value:
error:
type: invalid_request
message: >-
Only one identifier type can be provided. Found:
professional_network_profile_urls, business_emails
metadata: []
'401':
description: Unauthorized - invalid or missing API key
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error:
type: unauthorized
message: Invalid API key in request.
metadata: []
'403':
description: Permission denied or insufficient credits
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: No data found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
components:
parameters:
ApiVersion:
name: x-api-version
in: header
required: true
schema:
type: string
enum:
- '2025-11-01'
default: '2025-11-01'
example: '2025-11-01'
description: API version to use. This endpoint currently requires `2025-11-01`.
schemas:
PersonEnrichRequest:
type: object
properties:
professional_network_profile_urls:
type: array
items:
type: string
description: Array of professional-network profile URLs (max 25).
business_emails:
type: array
items:
type: string
format: email
description: Business email of the person to lookup
fields:
type: array
items:
type: string
description: >
Fields to include in the response. Valid field groups for enrich:
basic_profile, professional_network, skills, contact,
social_handles, experience, education, certifications, honors,
dev_platform_profiles. Use dot-notation for nested fields (e.g.,
"basic_profile.name", "experience.employment_details"). If omitted,
a default set (basic_profile, social_handles) is returned — request
additional groups explicitly. Some groups (for example
certifications and honors) require field-level permission on your
API key.
example:
- basic_profile
- experience
min_similarity_score:
type: number
minimum: 0
maximum: 1
nullable: true
description: Minimum similarity score for email matching
preview:
type: boolean
default: false
description: >-
Preview mode returns only basic profile fields and charges 0
credits. Cannot be combined with enrich_realtime.
oneOf:
- required:
- professional_network_profile_urls
- required:
- business_emails
additionalProperties: false
description: >-
Request body for /person/enrich and
/person/professional_network/enrich/live. Submit exactly one identifier
type per request — professional_network_profile_urls or business_emails.
example:
professional_network_profile_urls:
- https://www.linkedin.com/in/dvdhsu/
fields:
- basic_profile
PersonEnrichResponse:
type: array
items:
$ref: '#/components/schemas/PersonEnrichResult'
description: >-
Response from /person/enrich. Returns a top-level array with one entry
per submitted identifier.
example:
- matched_on: https://www.linkedin.com/in/dvdhsu/
match_type: professional_network_profile_url
matches: []
ErrorResponse:
type: object
description: >-
Standard error response returned by all Person API endpoints when a
request fails.
required:
- error
properties:
error:
type: object
required:
- type
- message
properties:
type:
type: string
enum:
- invalid_request
- authentication_error
- unauthorized
- insufficient_credits
- permission_error
- rate_limit_error
- internal_error
description: Category of the error
example: invalid_request
message:
type: string
description: Human-readable error message
example: 'Unsupported filter field: ''current_title'''
metadata:
type: array
items:
type: object
additionalProperties: true
default: []
description: >-
Additional structured context (e.g., available_fields,
sortable_fields)
PersonEnrichResult:
type: object
properties:
matched_on:
type: string
description: The specific input value (e.g., 'someone@company.com')
match_type:
type: string
enum:
- professional_network_profile_url
- business_email
matches:
type: array
items:
$ref: '#/components/schemas/PersonEnrichMatch'
description: One result entry in the enrich response — one per submitted identifier.
example:
matched_on: https://www.linkedin.com/in/dvdhsu/
match_type: professional_network_profile_url
matches:
- confidence_score: 1
person_data:
crustdata_person_id: 14540
basic_profile:
name: David Hsu
PersonEnrichMatch:
type: object
properties:
confidence_score:
type: number
format: float
example: 0.95
person_data:
$ref: '#/components/schemas/PersonEnrich'
description: >-
A single enriched person match from /person/enrich with confidence score
and full person data.
example:
confidence_score: 1
person_data:
crustdata_person_id: 14540
basic_profile:
name: David Hsu
PersonEnrich:
type: object
properties:
crustdata_person_id:
type: integer
basic_profile:
type: object
properties:
name:
type: string
headline:
type: string
first_name:
type: string
last_name:
type: string
current_title:
type: string
professional_network_name:
type: string
nullable: true
description: Display name on the person's professional-network profile.
example: David Hsu
normalized_title:
type: object
nullable: true
description: >-
Job Title Normalization (JTN, beta) — structured representation
of the person's current title mapped to Crustdata's proprietary
taxonomy (20 departments, 226 sub-departments). See
https://docs.crustdata.com/guides/job-title-normalization.
properties:
matched_title:
type: string
nullable: true
description: >-
Canonical normalized title matched to the person's current
title.
example: Co-Founder, CEO, CTO
department:
type: string
nullable: true
description: High-level department the normalized title maps to.
example: Executive Leadership
sub_department:
type: string
nullable: true
description: More granular classification within the department.
example: Founder & Entrepreneurship Leadership
similarity:
type: number
nullable: true
description: >-
Similarity score between the raw title and the matched
normalized title, from 0 to 1.
example: 0.6012
confident:
type: boolean
nullable: true
description: Whether the normalized-title match is considered confident.
example: true
summary:
type: string
languages:
type: array
items:
type: string
last_updated:
type: string
format: date-time
nullable: true
profile_picture_permalink:
type: string
nullable: true
location:
type: object
nullable: true
properties:
city:
type: string
nullable: true
state:
type: string
nullable: true
country:
type: string
nullable: true
continent:
type: string
nullable: true
raw:
type: string
nullable: true
professional_network:
type: object
properties:
profile_picture_url:
type: string
profile_picture_permalink:
type: string
name:
type: string
pronoun:
type: string
headline:
type: string
current_title:
type: string
summary:
type: string
location:
type: object
properties:
city:
type: string
nullable: true
state:
type: string
nullable: true
country:
type: string
nullable: true
continent:
type: string
nullable: true
raw:
type: string
nullable: true
connections:
type: integer
nullable: true
followers:
type: integer
nullable: true
joined_date:
type: string
nullable: true
verifications:
type: array
items:
type: string
open_to_cards:
type: array
description: >
Open-to signal codes declared on the profile. Filter with the
`in` operator using one or more of the closed enum values below.
Human-readable strings like `"open_to_work"` are not indexed and
return zero results.
| Code |
Meaning |
| ------------------ |
------------------------------------------------ |
| `CAREER_INTEREST` | Profile is open to new career
opportunities |
| `HIRING_MANAGER` | Profile is actively
hiring |
| `VOLUNTEERING` | Profile is open to volunteer
work |
items:
type: string
enum:
- CAREER_INTEREST
- HIRING_MANAGER
- VOLUNTEERING
example:
- CAREER_INTEREST
metadata:
type: object
properties:
last_scraped_source:
type: string
format: date-time
nullable: true
skills:
$ref: '#/components/schemas/PersonSkills'
contact:
$ref: '#/components/schemas/PersonEnrichContact'
social_handles:
type: object
properties:
professional_network_identifier:
type: object
properties:
profile_url:
type: string
dev_platform_identifier:
type: object
properties:
profile_url:
type: string
nullable: true
twitter_identifier:
type: object
properties:
slug:
type: string
dev_platform_profiles:
type: array
nullable: true
items:
$ref: '#/components/schemas/PersonDevPlatformProfile'
experience:
type: object
properties:
employment_details:
type: object
properties:
current:
type: array
items:
$ref: '#/components/schemas/PersonEmploymentDetails'
past:
type: array
items:
$ref: '#/components/schemas/PersonEmploymentDetails'
certifications:
type: array
items:
$ref: '#/components/schemas/PersonCertification'
description: >-
Certifications on the person profile. Requires field-level
permission on your API key.
honors:
type: array
items:
$ref: '#/components/schemas/PersonHonor'
description: >-
Honors and awards on the person profile. Requires field-level
permission on your API key.
education:
type: object
properties:
schools:
type: array
items:
$ref: '#/components/schemas/PersonEducation'
updated_at:
type: string
format: date-time
nullable: true
description: >-
Fully-enriched person profile with basic profile, skills, social
handles, experience, education, certifications, and contact.
example:
crustdata_person_id: 14540
basic_profile:
name: David Hsu
current_title: Founder, CEO
PersonSkills:
type: object
properties:
professional_network_skills:
type: array
items:
type: string
description: Skill signals from a person profile.
example:
professional_network_skills:
- Python
- Ruby
PersonEnrichContact:
type: object
properties:
business_emails:
type: array
items:
type: object
properties:
email:
type: string
status:
type: string
enum:
- verified
- unverified
last_updated:
type: string
format: date-time
nullable: true
crustdata_company_id:
type: integer
nullable: true
personal_emails:
type: array
items:
type: object
properties:
email:
type: string
status:
type: string
enum:
- verified
- unverified
last_updated:
type: string
format: date-time
nullable: true
phone_numbers:
type: array
items:
type: string
websites:
type: array
items:
type: string
description: >-
Contact details (emails, phone numbers) returned in person enrich
responses.
example:
business_emails: []
personal_emails: []
phone_numbers: []
PersonDevPlatformProfile:
type: object
description: One linked dev platform account profile
properties:
account_type:
type: string
nullable: true
profile_url:
type: string
nullable: true
name:
type: string
nullable: true
email:
type: string
nullable: true
location:
type: object
nullable: true
properties:
raw:
type: string
nullable: true
company_text:
type: string
nullable: true
bio:
type: string
nullable: true
website_url:
type: string
nullable: true
profile_picture_url:
type: string
nullable: true
is_hireable:
type: boolean
nullable: true
is_site_admin:
type: boolean
nullable: true
confidence_score:
type: number
format: double
nullable: true
public_repo_count:
type: integer
format: int64
nullable: true
followers:
type: integer
format: int64
nullable: true
following:
type: integer
format: int64
nullable: true
declared_handles:
type: array
nullable: true
items:
type: object
properties:
provider:
type: string
nullable: true
url:
type: string
nullable: true
created_at:
type: string
format: date-time
nullable: true
last_updated:
type: string
format: date-time
nullable: true
org_memberships:
type: array
nullable: true
items:
type: object
properties:
organization_id:
type: integer
format: int64
nullable: true
organization_github_id:
type: integer
format: int64
nullable: true
organization_login:
type: string
nullable: true
created_at:
type: string
format: date-time
nullable: true
last_updated:
type: string
format: date-time
nullable: true
metadata:
type: object
nullable: true
properties:
created_at:
type: string
format: date-time
nullable: true
last_scraped_source:
type: string
format: date-time
nullable: true
last_updated:
type: string
format: date-time
nullable: true
example:
account_type: github
profile_url: https://github.com/dvdhsu
PersonEmploymentDetails:
type: object
properties:
name:
type: string
nullable: true
professional_network_id:
type: string
nullable: true
title:
type: string
nullable: true
description:
type: string
nullable: true
location:
type: object
nullable: true
properties:
raw:
type: string
nullable: true
employment_type:
type: string
nullable: true
start_date:
type: string
nullable: true
end_date:
type: string
nullable: true
is_default:
type: boolean
nullable: true
crustdata_company_id:
type: integer
nullable: true
company_website_domain:
type: string
nullable: true
company_profile_picture_permalink:
type: string
nullable: true
description: >-
Stable Crustdata-hosted permalink to the company logo, suitable for
rendering in your own interface.
example: >-
https://crustdata-media.s3.us-east-2.amazonaws.com/company/72f60d0ccad488216922fb784abc89890b49eeed8ab1eca1a0a12c72a68a0620.jpg
company_professional_network_profile_url:
type: string
nullable: true
seniority_level:
type: string
nullable: true
function_category:
type: string
nullable: true
years_at_company:
type: string
nullable: true
years_at_company_raw:
type: number
nullable: true
company_headcount_latest:
type: integer
nullable: true
company_headcount_range:
type: string
nullable: true
company_industries:
type: array
nullable: true
items:
type: string
company_professional_network_industry:
type: string
nullable: true
company_type:
type: string
nullable: true
company_website:
type: string
nullable: true
company_headquarters_country:
type: string
nullable: true
company_hq_location:
type: string
nullable: true
company_hq_location_address_components:
type: array
nullable: true
items:
type: string
position_id:
type: integer
nullable: true
business_email_verified:
type: boolean
nullable: true
description: >-
Employment entry in a person profile — includes title, company, dates,
and function.
example:
name: Retool
title: Founder, CEO
start_date: '2017-01-01'
PersonCertification:
type: object
properties:
name:
type: string
issuing_organization:
type: string
issue_date:
type: string
nullable: true
expiration_date:
type: string
nullable: true
credential_id:
type: string
nullable: true
credential_url:
type: string
nullable: true
source:
type: string
description: Certification entry for a person profile.
example:
name: AWS Certified Solutions Architect
issuing_organization: Amazon Web Services
PersonHonor:
type: object
properties:
title:
type: string
nullable: true
issued_date:
type: string
nullable: true
description:
type: string
nullable: true
issuer:
type: string
nullable: true
media_urls:
type: array
nullable: true
items:
type: string
associated_organization:
type: string
nullable: true
associated_organization_professional_network_id:
type: string
nullable: true
description: Honor or award entry on a person profile.
example:
title: Dean's List
issuer: University of California, Berkeley
PersonEducation:
type: object
properties:
school:
type: string
description: Name of the educational institution.
example: University of Oxford
degree:
type: string
nullable: true
description: Degree earned at the institution.
example: Bachelor of Arts (B.A.)
field_of_study:
type: string
nullable: true
description: Primary field of study.
example: Philosophy, Politics and Economics
description:
type: string
nullable: true
description: >-
Free-text description of the education entry as it appears on the
profile. May be an empty string when no description is provided.
example: ''
location:
type: object
nullable: true
description: >-
Geographic location of the institution, resolved into structured
components.
properties:
raw:
type: string
nullable: true
description: Location string as it appears on the profile.
example: Oxford, England
city:
type: string
nullable: true
description: City component of the institution location.
example: Oxford
state:
type: string
nullable: true
description: State or region component of the institution location.
example: England
country:
type: string
nullable: true
description: Country component of the institution location.
example: United Kingdom
continent:
type: string
nullable: true
description: Continent component of the institution location.
example: Europe
start_year:
type: integer
nullable: true
description: Year the person started at the institution.
example: 2005
end_year:
type: integer
nullable: true
description: Year the person finished at the institution.
example: 2009
activities_and_societies:
type: string
nullable: true
description: Activities and societies the person participated in.
example: Debating Society
institute_logo_permalink:
type: string
nullable: true
description: >-
Stable Crustdata-hosted permalink to the institution logo, suitable
for rendering in your own interface.
example: >-
https://crustdata-media.s3.us-east-2.amazonaws.com/company/3d2093a16f7cf7b459a0d30d4e795d0be5a41a3396f21dee899e43e8a8b6de8d.jpg
institute_logo_url:
type: string
nullable: true
description: Source URL of the institution logo, when available.
example: https://media.example.com/logos/oxford.png
professional_network_id:
type: string
nullable: true
description: Identifier of the institution on the professional network.
example: '4477'
description: >-
Education entry in a person profile — school, degree, field of study,
location, and institution logo.
example:
school: University of Oxford
degree: Bachelor of Arts (B.A.)
location:
raw: Oxford, England
city: Oxford
state: England
country: United Kingdom
continent: Europe
institute_logo_permalink: >-
https://crustdata-media.s3.us-east-2.amazonaws.com/company/3d2093a16f7cf7b459a0d30d4e795d0be5a41a3396f21dee899e43e8a8b6de8d.jpg
professional_network_id: '4477'
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: API key passed as a Bearer token in the Authorization header.
````