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 Examples.

Filter operator reference

Person Search accepts the following filters.type operators.

Operator	Value shape	Meaning	Example use
`=`	scalar	Exact match	`basic_profile.name` = “David Hsu”
`!=`	scalar	Not equal	Exclude a specific country
`<`	scalar (number or date string)	Less than	Profiles updated before a timestamp
`=<`	scalar (number or date string)	Less than or equal	`professional_network.connections` at or below a threshold
`>`	scalar (number or date string)	Greater than	`years_of_experience_raw` above a threshold
`=>`	scalar (number or date string)	Greater than or equal	`professional_network.followers` at or above a threshold
`in`	array	Value is in list	`experience.employment_details.company_name` in [“Retool”, “OpenAI”]
`not_in`	array	Value is not in list	Exclude titles like “Intern”
`(.)`	string	Regex/contains match (case-insensitive)	Title contains “VP\|Director”
`(!)`	string	Fuzzy negation — exclude substring matches	Exclude titles containing “Intern” (see notes below)
`[.]`	string	Substring match	Title contains literal “SDR”
`geo_distance`	object	Within radius of a location or explicit coordinate	People within 50 km of San Francisco

Use => for greater-than-or-equal and =< for less-than-or-equal. The operators >= and <= are not supported.

`(!)` — fuzzy negation

(!) excludes profiles whose value contains the given substring, case-insensitive. It is the opposite of (.). Multi-word values are matched as a literal phrase — they are not word-split:

{ "type": "(!)", "value": "New York" } excludes only profiles that literally contain the phrase "New York". A profile whose location is "New Yorker" is not excluded by this filter; "New York City" is excluded because it contains the full phrase.

To exclude on each word independently, wrap multiple (!) conditions in an and group:

{
    "op": "and",
    "conditions": [
        {
            "field": "basic_profile.headline",
            "type": "(!)",
            "value": "Intern"
        },
        {
            "field": "basic_profile.headline",
            "type": "(!)",
            "value": "Student"
        }
    ]
}

`geo_distance` — radius around a point

Supply the centre of the radius using one of:

location — a string that is geocoded server-side (e.g. "San Francisco, CA").
lat_lng — explicit coordinates as [lat, lng]. Skips geocoding.

If both are supplied, lat_lng wins. distance is required; unit defaults to km.

Field	Type	Required	Notes
`location`	string	One of	Geocoded server-side. Ignored when `lat_lng` is also set.
`lat_lng`	number[]	One of	Two-element `[lat, lng]`. Lat in `[-90, 90]`, lng in `[-180, 180]`.
`distance`	number	Yes	Radius around the centre. Must be positive.
`unit`	string	No	One of `km`, `mi`, `miles`, `m`, `meters`, `ft`, `feet`. Defaults to `km`.

See geo_distance examples for end-to-end requests using both location and lat_lng.

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.

Country filters do not all use the same value format. Use full country names for person location fields, and use ISO 3166-1 alpha-3 codes for employer headquarters country fields.

Country and region value formats

Field	Value format	Examples
`basic_profile.location.country`	Full country name	`"United States"`, `"India"`
`basic_profile.location.state`	Full state or region name	`"California"`, `"Ontario"`
`basic_profile.location.continent`	Full continent name	`"North America"`, `"Asia"`
`professional_network.location.raw`	Raw location string	`"San Francisco Bay Area"`
`experience.employment_details.company_headquarters_country`	ISO 3166-1 alpha-3 country code	`"USA"`, `"IND"`
`experience.employment_details.current.company_headquarters_country`	ISO 3166-1 alpha-3 country code	`"USA"`, `"GBR"`
`experience.employment_details.past.company_headquarters_country`	ISO 3166-1 alpha-3 country code	`"IND"`, `"USA"`
`experience.employment_details.company_hq_location`	Employer HQ location string	`"San Francisco, California"`

For headquarters country filters, use ISO-3 codes such as USA, IND, and GBR. For the full code list, see the ISO 3166-1 alpha-3 country code list. For basic_profile.location.country, use Autocomplete to discover indexed full-country labels before filtering.

Identity & metadata

Field	Type	Sortable	Description
`crustdata_person_id`	integer	Yes	Crustdata person ID
`metadata.updated_at`	datetime	Yes	Last profile update timestamp
`metadata.last_scraped_source`	string	No	Last profile refresh source

Basic profile

Field	Type	Sortable	Description
`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.last_updated`	datetime	No	Last update timestamp on the basic profile
`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 as a full name
`basic_profile.location.country`	string	Yes	Country as a full name
`basic_profile.location.continent`	string	No	Continent as a full name
`basic_profile.normalized_title.department`	string	No	Job Title Normalization (beta) — high-level department.
`basic_profile.normalized_title.sub_department`	string	No	Job Title Normalization (beta) — sub-department / category.
`basic_profile.normalized_title.matched_title`	string	No	Job Title Normalization (beta) — standardized canonical title.
`basic_profile.normalized_title.similarity`	float	No	Job Title Normalization (beta) — similarity score between raw and matched title.
`basic_profile.normalized_title.confident`	boolean	No	Job Title Normalization (beta) — whether the mapping is high-confidence.
`basic_profile.professional_network_name`	string	No	Display name on the professional-network profile

Professional network

Field	Type	Sortable	Description
`professional_network.location.raw`	string	No	Raw location string from profile
`professional_network.location`	string	No	Network location summary
`professional_network.location.city`	string	No	Network location city
`professional_network.location.state`	string	No	Network location state / region
`professional_network.location.country`	string	No	Network location country
`professional_network.location.continent`	string	No	Network location continent
`professional_network.connections`	integer	Yes	Connection count
`professional_network.followers`	integer	Yes	Follower count (requires API key access)
`professional_network.open_to_cards`	string[]	No	Open-to signal codes. See Open-to signal values
`professional_network.metadata.last_scraped_source`	string	No	Last profile refresh source

Skills

Field	Type	Sortable	Description
`skills.professional_network_skills`	string[]	No	Listed skills

Experience — all employers

Field	Type	Sortable	Description
`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.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 as ISO-3 code
`experience.employment_details.company_hq_location`	string	No	Employer HQ location string
`experience.employment_details.company_website`	string	No	Employer website across all roles
`experience.employment_details.employment_type`	string	No	Employment type across all roles
`experience.employment_details.years_at_company_raw`	number	No	Years at company across all roles
`experience.employment_details.business_email_verified`	boolean	No	Verified business email across all roles

Experience — current employer

Field	Type	Sortable	Description
`experience.employment_details.current.company_name`	string	No	Current company name (filter alias of `current.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 company name (returned response field)
`experience.employment_details.current.years_at_company_raw`	number	No	Years at current company
`experience.employment_details.current.company_headquarters_country`	string	No	Current employer HQ country as ISO-3 code
`experience.employment_details.current.company_id`	integer	No	Current employer company ID
`experience.employment_details.current.position_id`	string	No	Per-role identifier for the current position (one per role, distinct from company ID)
`experience.employment_details.current.company_industries`	string[]	No	Current employer industries
`experience.employment_details.current.company_type`	string	No	Current employer company type
`experience.employment_details.current.company_headcount_latest`	integer	No	Current employer latest headcount
`experience.employment_details.current.company_headcount_range`	string	No	Current employer headcount range
`experience.employment_details.current.company_hq_location`	string	No	Current employer HQ location string
`experience.employment_details.current.company_website_domain`	string	No	Current employer website domain
`experience.employment_details.current.company_professional_network_industry`	string	No	Current employer primary industry label
`experience.employment_details.current.company_professional_network_profile_url`	string	No	Current employer profile URL. Exact full URL — see Find people at a company
`experience.employment_details.current.company_linkedin_profile_url`	string	No	Current employer profile URL (accepted alias)
`experience.employment_details.current.employment_type`	string	No	Current employment type
`experience.employment_details.current.business_email_verified`	boolean	No	Verified business email on current role

Experience — past employer

Field	Type	Sortable	Description
`experience.employment_details.past.company_name`	string	No	Past company name (filter alias of `past.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 company name (returned response field)
`experience.employment_details.past.years_at_company_raw`	number	No	Years at past company
`experience.employment_details.past.company_headquarters_country`	string	No	Past employer HQ country as ISO-3 code
`experience.employment_details.past.company_id`	integer	No	Past employer company ID
`experience.employment_details.past.position_id`	string	No	Per-role identifier for the past position (one per role, distinct from company ID)
`experience.employment_details.past.company_industries`	string[]	No	Past employer industries
`experience.employment_details.past.company_type`	string	No	Past employer company type
`experience.employment_details.past.company_headcount_latest`	integer	No	Past employer latest headcount
`experience.employment_details.past.company_headcount_range`	string	No	Past employer headcount range
`experience.employment_details.past.company_hq_location`	string	No	Past employer HQ location string
`experience.employment_details.past.company_website_domain`	string	No	Past employer website domain
`experience.employment_details.past.company_professional_network_industry`	string	No	Past employer primary industry label
`experience.employment_details.past.company_professional_network_profile_url`	string	No	Past employer profile URL. Exact full URL — see Find people at a company
`experience.employment_details.past.company_linkedin_profile_url`	string	No	Past employer profile URL (accepted alias)
`experience.employment_details.past.employment_type`	string	No	Past employment type
`experience.employment_details.past.business_email_verified`	boolean	No	Verified business email on past role

Education

Field	Type	Sortable	Description
`education.schools.school`	string	No	School name
`education.schools.degree`	string	No	Degree
`education.schools.field_of_study`	string	No	Field of study
`education.schools.location`	string	No	School location summary
`education.schools.location.city`	string	No	School location city
`education.schools.location.state`	string	No	School location state / region
`education.schools.location.country`	string	No	School location country
`education.schools.location.continent`	string	No	School location continent
`education.schools.location.full_location`	string	No	School full location string

Certifications & honors

Field	Type	Sortable	Description
`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
`certifications.credential_id`	string	No	Certification credential ID
`certifications.credential_url`	string	No	Certification credential URL
`honors.title`	string	No	Honor or award title

Field	Type	Sortable	Description
`social_handles.twitter_handle`	string	No	Twitter/X handle

Other

Field	Type	Sortable	Description
`recently_changed_jobs`	boolean	No	True if the profile recently changed jobs
`years_of_experience_raw`	number	No	Total years of experience (precise)
`years_of_experience`	number	No	Total years of experience (rounded)

Open-to signal values

professional_network.open_to_cards is a closed enum of exactly three code strings. Filter with the in operator using one or more of these values:

Code	Meaning
`CAREER_INTEREST`	Profile is open to new career opportunities
`HIRING_MANAGER`	Profile is actively hiring
`VOLUNTEERING`	Profile is open to volunteer work

Only the three uppercase code strings above are indexed. Human-readable strings like "open_to_work" or "Open to Work" return zero results. Always use the codes as-is.

Filter example

{
    "filters": {
        "op": "and",
        "conditions": [
            {
                "field": "professional_network.open_to_cards",
                "type": "in",
                "value": ["CAREER_INTEREST"]
            }
        ]
    },
    "limit": 5
}

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`, `normalized_title`, `professional_network_name`, `location`, `summary`	Identity and location
`experience`	`employment_details.current`, `employment_details.past` (each role includes `company_profile_picture_permalink`)	Full work history
`education`	`schools` (each includes `school`, `degree`, `location`, `description`, `institute_logo_permalink`)	Education background
`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`, `followers`, `profile_picture_permalink`	Network metadata

skills.professional_network_skills is filterable but is not returned by Person Search (lightweight discovery). To retrieve skills, use Person Enrich. dev_platform_profiles is likewise not returned by search.

Request parameter reference

Parameter	Type	Required	Default	Description
`filters`	object	Yes	—	Filter condition or condition group. See operators above.
`fields`	string[]	No	Default set	Dot-path fields or section groups to return (e.g., `["basic_profile.name", "experience.employment_details.current.title"]`). When omitted, the default profile sections are returned. `skills` and `dev_platform_profiles` are not returned by search.
`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`

Paginate through results

When your search matches more profiles than your limit, use cursor-based pagination to walk through all pages. First page: send your normal search request.

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.company_name",
      "type": "in",
      "value": ["Retool"]
    },
    "limit": 100
  }'

Next page: take the next_cursor value from the response and pass it in your next request. Keep the same filters and limit.

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.company_name",
      "type": "in",
      "value": ["Retool"]
    },
    "limit": 100,
    "cursor": "PASTE_NEXT_CURSOR_VALUE_HERE"
  }'

Continue until next_cursor is null, which means you have reached the last page.

Always include sorts when paginating to ensure stable ordering across pages.

Sort results

Use the sorts parameter to order results by a specific field. This is important for stable pagination.

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.current.title",
      "type": "=",
      "value": "CEO"
    },
    "sorts": [{"field": "professional_network.connections", "order": "desc"}],
    "limit": 5,
    "fields": ["basic_profile.name", "professional_network.connections"]
  }'

Valid sortable fields include: crustdata_person_id, basic_profile.name, professional_network.connections, professional_network.followers, experience.employment_details.start_date, experience.employment_details.company_id, metadata.updated_at. For the full list of searchable (and sortable) fields, see Search reference. See the full API reference for the complete OpenAPI schema

​Filter operator reference

​(!) — fuzzy negation

​geo_distance — radius around a point

​Searchable fields

​Country and region value formats

​Identity & metadata

​Basic profile

​Professional network

​Skills

​Experience — all employers

​Experience — current employer

​Experience — past employer

​Education

​Certifications & honors

​Social handles

​Other

​Open-to signal values

​Response fields

​Request parameter reference

​Preview mode

Preview mode

​Errors

​No results

​API reference summary

​Paginate through results

​Sort results

Filter operator reference

`(!)` — fuzzy negation

`geo_distance` — radius around a point

Searchable fields

Country and region value formats

Identity & metadata

Basic profile

Professional network

Skills

Experience — all employers

Experience — current employer

Experience — past employer

Education

Certifications & honors

Social handles

Other

Open-to signal values

Response fields

Request parameter reference

Preview mode

Errors

No results

API reference summary

Paginate through results

Sort results