> ## 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 Search reference
> Reference for Person Search: filter operators, searchable fields, response fields, request parameters, preview mode, and errors.
Reference material for [Person Search](/person-docs/search/introduction): 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](/person-docs/search/introduction) and
[Examples](/person-docs/search/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:
```json theme={"theme":"vitesse-black"}
{
"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](/person-docs/search/examples#search-within-a-geographic-radius)
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](/person-docs/enrichment/introduction) 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](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3).
For `basic_profile.location.country`, use [Autocomplete](/person-docs/autocomplete/introduction)
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](/guides/job-title-normalization) (beta) — high-level department. |
| `basic_profile.normalized_title.sub_department` | string | No | [Job Title Normalization](/guides/job-title-normalization) (beta) — sub-department / category. |
| `basic_profile.normalized_title.matched_title` | string | No | [Job Title Normalization](/guides/job-title-normalization) (beta) — standardized canonical title. |
| `basic_profile.normalized_title.similarity` | float | No | [Job Title Normalization](/guides/job-title-normalization) (beta) — similarity score between raw and matched title. |
| `basic_profile.normalized_title.confident` | boolean | No | [Job Title Normalization](/guides/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](#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](/person-docs/search/examples#find-people-at-a-company-by-its-profile-url) |
| `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](/person-docs/search/examples#find-people-at-a-company-by-its-profile-url) |
| `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 |
### Social handles
| 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.
```json Filter example theme={"theme":"vitesse-black"}
{
"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](/person-docs/enrichment/introduction).
`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](#filter-operator-reference) 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](#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.`
```bash Preview search theme={"theme":"vitesse-black"}
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:
```json theme={"theme":"vitesse-black"}
{
"profiles": [],
"next_cursor": null,
"total_count": 0
}
```
**Action:** Broaden filters or check field values with [Autocomplete](/person-docs/autocomplete/introduction).
***
## 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.
```bash First page theme={"theme":"vitesse-black"}
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`.
```bash Next page theme={"theme":"vitesse-black"}
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.
```bash Sort by connections (descending) theme={"theme":"vitesse-black"}
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](/person-docs/search/reference#searchable-fields).
See the [full API reference](/openapi-specs/2025-11-01/introduction) for the complete OpenAPI schema