Person Search reference - Crustdata Docs

Reference material for Person Search: the full list of filter operators, searchable fields with sortable flags, response fields, request parameters, preview mode, and error responses. For walk-through examples, see Person Search and Filter recipes.

Filter operator reference

Operator	Meaning	Example use
`=`	Exact match	`basic_profile.name` = “David Hsu”
`!=`	Not equal	Exclude a specific country
`>` / `<`	Greater/less than	Numeric comparisons
`in`	Value is in list	`experience.employment_details.company_name` in [“Retool”, “OpenAI”]
`not_in`	Value is not in list	Exclude titles like “Intern”
`(.)`	Regex/contains match	Title contains “VP\|Director”
`geo_distance`	Within radius of location	People near San Francisco

Searchable fields

Some returned fields use a different filter path. For example, the returned basic_profile.current_title is searched with experience.employment_details.current.title.
Contact availability flags such as contact.has_business_email are response-only convenience fields. For search filters, use experience.employment_details.current.business_email_verified, experience.employment_details.past.business_email_verified, or experience.employment_details.business_email_verified.
social_handles.professional_network_identifier.profile_url is returned in search results but is rejected as a search filter. Use Person Enrich for direct profile URL lookups.
Some searchable fields, such as certifications.* and honors.title, may not appear in the response summary below.

Field	Type	Sortable	Description
`crustdata_person_id`	integer	Yes	Crustdata person ID
`metadata.updated_at`	datetime	Yes	Last profile update timestamp
`basic_profile.name`	string	Yes	Full name
`basic_profile.first_name`	string	No	First name
`basic_profile.last_name`	string	No	Last name
`basic_profile.headline`	string	No	Profile headline
`basic_profile.summary`	string	No	Profile summary / about
`basic_profile.languages`	string[]	No	Spoken languages
`basic_profile.location`	string	Yes	Location summary
`basic_profile.location.full_location`	string	Yes	Full location string
`basic_profile.location.city`	string	Yes	City
`basic_profile.location.state`	string	Yes	State / region
`basic_profile.location.country`	string	Yes	Country
`basic_profile.location.continent`	string	No	Continent
`professional_network.location.raw`	string	No	Raw location string from profile
`professional_network.connections`	integer	Yes	Connection count
`professional_network.open_to_cards`	string[]	No	Open-to signals (e.g., `"open_to_work"`)
`professional_network.metadata.last_scraped_source`	string	No	Last profile refresh source
`skills.professional_network_skills`	string[]	No	Listed skills
`experience.employment_details.company_name`	string	No	Company name across all roles
`experience.employment_details.title`	string	No	Job title across all roles
`experience.employment_details.description`	string	No	Role description across all roles
`experience.employment_details.seniority_level`	string	No	Seniority level across all roles
`experience.employment_details.function_category`	string	No	Function category across all roles
`experience.employment_details.start_date`	date	Yes	Role start date across all roles
`experience.employment_details.end_date`	date	No	Role end date across all roles
`experience.employment_details.location`	string	No	Role location across all roles
`experience.employment_details.company_id`	integer	Yes	Company ID across all roles
`experience.employment_details.current.company_name`	string	No	Current company name
`experience.employment_details.current.title`	string	No	Current job title
`experience.employment_details.current.seniority_level`	string	No	Current seniority level
`experience.employment_details.current.function_category`	string	No	Current function category
`experience.employment_details.current.start_date`	date	No	Current role start date
`experience.employment_details.current.name`	string	No	Current role name
`experience.employment_details.current.years_at_company_raw`	number	No	Years at current company
`experience.employment_details.past.company_name`	string	No	Past company name
`experience.employment_details.past.title`	string	No	Past job title
`experience.employment_details.past.seniority_level`	string	No	Past seniority level
`experience.employment_details.past.function_category`	string	No	Past function category
`experience.employment_details.past.start_date`	date	No	Past role start date
`experience.employment_details.past.name`	string	No	Past role name
`experience.employment_details.past.years_at_company_raw`	number	No	Years at past company
`experience.employment_details.company_website_domain`	string	No	Employer website domain
`experience.employment_details.company_headcount_latest`	integer	No	Employer latest headcount
`experience.employment_details.company_headcount_range`	string	No	Employer headcount range
`experience.employment_details.company_industries`	string[]	No	Employer industries
`experience.employment_details.company_professional_network_industry`	string	No	Employer primary industry label
`experience.employment_details.company_type`	string	No	Employer company type
`experience.employment_details.company_headquarters_country`	string	No	Employer HQ country
`experience.employment_details.company_hq_location`	string	No	Employer HQ location string
`experience.employment_details.business_email_verified`	boolean	No	Verified business email across all roles
`experience.employment_details.current.business_email_verified`	boolean	No	Verified business email on current role
`experience.employment_details.past.business_email_verified`	boolean	No	Verified business email on past role
`education.schools.school`	string	No	School name
`education.schools.degree`	string	No	Degree
`education.schools.field_of_study`	string	No	Field of study
`certifications.name`	string	No	Certification name
`certifications.issuing_organization`	string	No	Certification issuer
`certifications.issue_date`	date	No	Certification issue date
`certifications.expiration_date`	date	No	Certification expiration date
`honors.title`	string	No	Honor or award title
`recently_changed_jobs`	boolean	No	True if the profile recently changed jobs
`years_of_experience_raw`	number	No	Total years of experience

Response fields

Each profile in the response can include these sections, depending on fields. This table summarizes returned sections only. It is not a complete filter reference.

Section	Key fields	Description
`basic_profile`	`name`, `headline`, `current_title`, `location`, `summary`	Identity and location
`experience`	`employment_details.current`, `employment_details.past`	Full work history
`education`	`schools`	Education background
`skills`	`professional_network_skills`	Listed skills
`contact`	`has_business_email`, `has_personal_email`, `has_phone_number`	Contact availability flags
`social_handles`	`professional_network_identifier.profile_url`, `dev_platform_identifier.profile_url`, `twitter_identifier.slug`	Available profile handles
`professional_network`	`connections`, `profile_picture_permalink`	Network metadata

Request parameter reference

Parameter	Type	Required	Default	Description
`filters`	object	Yes	—	Filter condition or condition group. See operators above.
`fields`	string[]	No	All	Dot-path fields to return (e.g., `["basic_profile.name", "experience.employment_details.current.title"]`).
`sorts`	array	No	`[]`	Sort specifications as an array of `{ field, order }` objects. Use `asc` or `desc` for `order`. Required for stable pagination.
`limit`	integer	No	20	Max profiles per page (1–1000).
`count`	integer	No	—	Alias for `limit`.
`cursor`	string	No	`null`	Pagination cursor from previous response’s `next_cursor`.
`post_processing`	object	No	—	`exclude_profiles` (URL array) and `exclude_names` (name array).
`preview`	boolean	No	`false`	Premium feature — see Preview mode.
`return_query`	boolean	No	`false`	Debug flag accepted by the API. Current platform behavior: the response does not include a top-level `query` field.

Preview mode

Preview search is a premium feature. Book a demo to enable it for your account.

If preview access is enabled for your account, use preview: true to get lightweight results before running a full search. Preview responses keep the same top-level shape but may return fewer profile fields.

Current platform behavior: if preview is not enabled for your account, the API returns 400 invalid_request with the message error: PersonDB preview feature is not available for your account.

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": {
      "field": "experience.employment_details.title",
      "type": "(.)",
      "value": "Founder"
    },
    "preview": true,
    "limit": 2
  }'

Errors

Status	Meaning
`400`	Invalid request — unsupported field, wrong operator, malformed filters, or preview not enabled for your account.
`401`	Invalid or missing API key.
`403`	Permission denied or insufficient credits.
`500`	Internal server error. Retry with exponential backoff.

No results

When no people match the filters, the API returns 200 with an empty profiles array:

{
    "profiles": [],
    "next_cursor": null,
    "total_count": 0
}

Action: Broaden filters or check field values with Autocomplete.

API reference summary

Detail	Value
Endpoint	`POST /person/search`
Auth	Bearer token + `x-api-version: 2025-11-01`
Response	`{ "profiles": [...], "next_cursor": "...", "total_count": N }`
Pagination	Cursor-based. Pass `next_cursor` as `cursor`. Stop when `next_cursor` is `null`.
Errors	`400`, `401`, `403`, `500`

See the full API reference for the complete OpenAPI schema.

​Filter operator reference

​Searchable fields

​Response fields

​Request parameter reference

​Preview mode

Preview mode

​Errors

​No results

​API reference summary

Filter operator reference

Searchable fields

Response fields

Request parameter reference

Preview mode

Errors

No results

API reference summary