> ## 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

> Learn how to search for people using the Person Search API, from simple name lookups to multi-filter queries.

The Person Search API lets you find professionals by name, title, company, location, and more. This page walks you through the basics: your first search, the response shape, and combining filters — plus worked example recipes you can copy, paste, and adapt. For the operator list, field catalog, and validation rules, see [Search reference](/person-docs/search/reference).

Every request goes to the same endpoint:

```
POST https://api.crustdata.com/person/search
```

<Note>
  Replace `YOUR_API_KEY` in each example with your actual API key. All
  requests require the `x-api-version: 2025-11-01` header.
</Note>

<Callout icon="coins" color="#5345e4">
  <strong>Pricing:</strong> <code>0.03 credits per result returned</code>.
</Callout>

<Tip>
  **Looking for the list of fields you can filter on?** See [Searchable
  fields](/person-docs/search/reference#searchable-fields) in the search
  reference for the full table of `filters.field` values grouped by family,
  plus a one-line trick to fetch the live list from the API.
</Tip>

<CardGroup cols={3}>
  <Card title="Examples" icon="list-filter" href="#example-requests">
    Employer + title, geo radius, country, and post-processing exclusions.
  </Card>

  <Card title="Pagination & sorting" icon="list-ordered" href="/person-docs/search/reference#paginate-through-results">
    Cursor-based pagination and sort rules for stable ordering.
  </Card>

  <Card title="Reference" icon="book" href="/person-docs/search/reference">
    Operators, searchable fields, response fields, preview mode, errors.
  </Card>
</CardGroup>

***

## Your first search: find a person by name

The simplest search finds a person by their exact name. You pass a single filter with the `=` operator.

<CodeGroup>
  ```bash Request 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": "basic_profile.name",
        "type": "=",
        "value": "Abhilash Chowdhary"
      },
      "limit": 1
    }'
  ```

  ```json Response theme={"theme":"vitesse-black"}
  {
      "profiles": [
          {
              "crustdata_person_id": 1068035,
              "basic_profile": {
                  "name": "Abhilash Chowdhary",
                  "headline": "Co-founder at Crustdata (YC F24) | Real-time B2B data for AI agents",
                  "location": {
                      "raw": "San Francisco, California, United States",
                      "city": "San Francisco",
                      "state": "California",
                      "country": "United States of America",
                      "continent": "North America"
                  }
              },
              "social_handles": {
                  "professional_network_identifier": {
                      "profile_url": "https://www.linkedin.com/in/abhilashchowdhary"
                  }
              },
              "experience": {
                  "employment_details": {
                      "current": [
                          {
                              "name": "Crustdata (YC F24)",
                              "title": "Co-Founder & CEO"
                          }
                      ],
                      "past": [
                          {
                              "name": "Serve Robotics",
                              "title": "Engineering Manager, Motion Planning and Controls"
                          },
                          {
                              "name": "Postmates by Uber",
                              "title": "Robotics Lead, Motion Planning and Controls"
                          }
                      ]
                  }
              },
              "education": {
                  "schools": [
                      {
                          "school": "Virginia Tech",
                          "degree": "Master’s Degree"
                      },
                      {
                          "school": "IIIT Hyderabad",
                          "degree": "Bachelor of Technology (B.Tech.)"
                      },
                      {
                          "school": "Y Combinator",
                          "degree": "F24 Batch"
                      }
                  ]
              }
          }
      ],
      "next_cursor": "H4sIAG6-oWkC_xXMMQrDMAxA0a...",
      "total_count": 8
  }
  ```
</CodeGroup>

<Note>Response trimmed for clarity.</Note>

### Understanding the response

Every search response has three fields:

* **`profiles`** — an array of matching people. Each profile contains identity fields, education, profile handles, and contact availability flags for the fields you requested.
* **`total_count`** — how many people match your filters across the full database. Here, 8 people named "Abhilash Chowdhary" exist.
* **`next_cursor`** — a pagination token. Pass it in the next request to get the next page of results. `null` means there are no more pages.

***

## Combine filters with `and`

Real searches need more than one criterion. Wrap multiple conditions inside an `op: "and"` group to require all of them.

This search finds Co-Founders located in San Francisco. The `(.)` operator does a fuzzy token match instead of an exact match. This makes it tolerant to typos.

<CodeGroup>
  ```bash Request 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": {
        "op": "and",
        "conditions": [
          {
            "field": "experience.employment_details.title",
            "type": "(.)",
            "value": "Co-Founder"
          },
          {
            "field": "basic_profile.location.full_location",
            "type": "(.)",
            "value": "San Francisco"
          }
        ]
      },
      "limit": 2
    }'
  ```

  ```json Response theme={"theme":"vitesse-black"}
  {
      "profiles": [
          {
              "crustdata_person_id": 1279,
              "basic_profile": {
                  "name": "Dipesh Garg",
                  "headline": "CEO at Truelancer | 2 Million+ Professionals",
                  "location": {
                      "raw": "San Francisco, California, United States"
                  }
              },
              "experience": {
                  "employment_details": {
                      "current": [
                          {
                              "name": "Truelancer.com",
                              "title": "CEO & Founder"
                          }
                      ],
                      "past": [
                          {
                              "name": "MyRemoteTeam Inc",
                              "title": "Founder"
                          },
                          {
                              "name": "MyRemoteTeam Inc",
                              "title": "Lead Developer"
                          }
                      ]
                  }
              }
          }
      ],
      "next_cursor": "H4sIAHC-oWkC_xWMMQ7CMAwAv...",
      "total_count": 95577
  }
  ```
</CodeGroup>

<Note>Response trimmed for clarity.</Note>

The key difference from the first example: instead of a single `filters` object, you now have a group with `op: "and"` and a `conditions` array. Every condition must match for a profile to be included.

For more filter patterns (employer + title, geo radius, excludes), see the
[example requests](#example-requests) below. To walk through large result
sets, see [Pagination and sorting](/person-docs/search/reference#paginate-through-results).

***

## Read normalized titles and education details

Each profile also returns a normalized title classification and structured education — including school location and a Crustdata-hosted institution logo. Request the sections you need with `fields`, and filter by `crustdata_person_id` to fetch a single person.

<CodeGroup>
  ```bash Request 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": "crustdata_person_id", "type": "=", "value": 14540 },
      "fields": ["crustdata_person_id", "basic_profile", "education"],
      "limit": 1
    }'
  ```

  ```json Response theme={"theme":"vitesse-black"}
  {
      "profiles": [
          {
              "crustdata_person_id": 14540,
              "basic_profile": {
                  "name": "David Hsu",
                  "current_title": "Founder, CEO",
                  "normalized_title": {
                      "matched_title": "Co-Founder, CEO, CTO",
                      "department": "Executive Leadership",
                      "sub_department": "Founder & Entrepreneurship Leadership",
                      "similarity": 0.6012,
                      "confident": true
                  }
              },
              "education": {
                  "schools": [
                      {
                          "school": "University of Oxford",
                          "degree": "Bachelor of Arts (B.A.)",
                          "location": {
                              "raw": "South Hinksey, Wootton, Kennington, Oxford, Boars Hill, England, United Kingdom",
                              "city": "Boars Hill",
                              "state": "England",
                              "country": "United Kingdom",
                              "continent": "Europe"
                          },
                          "institute_logo_permalink": "https://crustdata-media.s3.us-east-2.amazonaws.com/company/3d2093a16f7cf7b459a0d30d4e795d0be5a41a3396f21dee899e43e8a8b6de8d.jpg"
                      }
                  ]
              }
          }
      ],
      "next_cursor": "H4sIAAFsGWoC_x...",
      "total_count": 1
  }
  ```
</CodeGroup>

<Note>
  `basic_profile.normalized_title` and `education.schools.location` are
  **filterable** but not sortable. `professional_network.followers` and
  `professional_network.connections` are **filterable and sortable**, but they
  are **not returned** in the search response — use them to narrow or rank
  results, not to read counts. School `description` and
  `institute_logo_permalink` are returned for display only.
</Note>

***

## Example Requests

Common filter patterns for Person Search. Each is a full, tested request
against `POST /person/search` that you can copy, paste, and adapt. Click any
row to expand it.

<AccordionGroup>
  <Accordion title="1. Basic filter examples">
    Find people by exact title match:

    ```bash 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": "Chief Executive Officer"
        },
        "limit": 100
      }'
    ```

    <Warning>
      **`=` and `in` match the full title string exactly.** `"Chief Information
                Security Officer"` will not match people titled "Deputy Chief Information
      Security Officer" or "SVP and CISO". For substring or word matching — the
      common case for titles — use the `(.)` operator, as in the next example.
    </Warning>

    Find people whose headline contains "founder" (case-insensitive contains match):

    ```bash 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": "basic_profile.headline", "type": "(.)", "value": "founder" },
        "limit": 100
      }'
    ```

    Find people with more than 10 years of experience:

    ```bash 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": "years_of_experience_raw", "type": ">", "value": 10 },
        "limit": 100
      }'
    ```
  </Accordion>

  <Accordion title="2. Filter with comparison operators">
    Find well-connected people who recently changed jobs:

    ```bash 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": {
          "op": "and",
          "conditions": [
            { "field": "professional_network.connections", "type": ">", "value": 500 },
            { "field": "recently_changed_jobs", "type": "=", "value": true }
          ]
        },
        "limit": 50
      }'
    ```
  </Accordion>

  <Accordion title="3. Filter with NOT operators">
    Find professionals in a region, excluding certain employers and titles:

    ```bash 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": {
          "op": "and",
          "conditions": [
            { "field": "experience.employment_details.current.company_name", "type": "not_in", "value": ["Google", "Meta", "Amazon"] },
            { "field": "experience.employment_details.current.title", "type": "!=", "value": "Intern" },
            { "field": "professional_network.location.raw", "type": "=", "value": "San Francisco Bay Area" }
          ]
        },
        "limit": 100
      }'
    ```
  </Accordion>

  <Accordion title="4. Complex nested filter example">
    Find senior people (VP, Director, or CXO) with 10+ years of experience at companies under 1,000 employees:

    ```bash 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": {
          "op": "and",
          "conditions": [
            {
              "op": "or",
              "conditions": [
                { "field": "experience.employment_details.current.title", "type": "(.)", "value": "VP" },
                { "field": "experience.employment_details.current.title", "type": "(.)", "value": "Director" },
                { "field": "experience.employment_details.current.seniority_level", "type": "=", "value": "CXO" }
              ]
            },
            { "field": "years_of_experience_raw", "type": "=>", "value": 10 },
            { "field": "experience.employment_details.current.company_headcount_latest", "type": "<", "value": 1000 }
          ]
        },
        "limit": 50
      }'
    ```
  </Accordion>

  <Accordion title="5. Filter by date ranges">
    Find people who started a role at a public company since 2023:

    ```bash 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": {
          "op": "and",
          "conditions": [
            { "field": "experience.employment_details.current.start_date", "type": "=>", "value": "2023-01-01" },
            { "field": "experience.employment_details.current.company_type", "type": "=", "value": "Public Company" },
            { "field": "years_of_experience_raw", "type": "=<", "value": 15 }
          ]
        },
        "limit": 50
      }'
    ```
  </Accordion>

  <Accordion title="6. Filter by education and skills">
    Find Stanford alumni (non-Bachelor degree) skilled in machine learning:

    ```bash 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": {
          "op": "and",
          "conditions": [
            { "field": "education.schools.school", "type": "(.)", "value": "Stanford" },
            { "field": "education.schools.degree", "type": "!=", "value": "Bachelor" },
            { "field": "skills.professional_network_skills", "type": "(.)", "value": "machine learning" }
          ]
        },
        "limit": 100
      }'
    ```
  </Accordion>
</AccordionGroup>

***

## Semantic search (natural language)

Instead of hand-building filters, pass a natural-language `search.query` to rank
people by overall profile meaning. `search.mode` controls how matching works —
including a **keyword (lexical)** mode and a **semantic** mode:

| `search.mode`      | What it does                                                       |
| ------------------ | ------------------------------------------------------------------ |
| `hybrid` (default) | Combines keyword (lexical) and semantic vector matching            |
| `lexical`          | Keyword matching only — exact terms, acronyms, tools, names        |
| `semantic`         | Vector similarity only — concept matching across different wording |

Every result carries a relevance `fit` tier (`strong`, `possible`, or `weak`).
Responses use the standard Person Search shape plus `fit` and
`total_count_relation`:

```json Response shape theme={"theme":"vitesse-black"}
{
  "profiles": [
    {
      "crustdata_person_id": 123,
      "fit": "strong",
      "basic_profile": { "name": "Example Person", "current_title": "Founding Engineer" }
    }
  ],
  "next_cursor": "H4sIA...",
  "total_count": 1250,
  "total_count_relation": "eq"
}
```

<Note>
  Semantic search is in **beta**. Don't send `sorts` — results are already
  rank-ordered by relevance. For recall modes (`managed` vs `exact`) and the
  full behavior, see the
  [Person Semantic Search guide](/guides/person-semantic-search).
</Note>

<AccordionGroup>
  <Accordion title="Natural-language query (hybrid: keyword + semantic)">
    The default. Describe who you want in plain language; `hybrid` blends keyword and
    semantic matching for the best general-purpose recall.

    ```bash 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 '{
        "search": { "query": "founding engineers at developer tools startups", "mode": "hybrid" },
        "fields": ["fit", "basic_profile", "experience.employment_details.current"],
        "limit": 5
      }'
    ```
  </Accordion>

  <Accordion title="Keyword search (lexical mode)">
    Use `lexical` when exact terms, acronyms, tools, or names should dominate —
    keyword matching only, no vector similarity.

    ```bash 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 '{
        "search": { "query": "Golang Kubernetes platform engineer", "mode": "lexical" },
        "fields": ["fit", "basic_profile"],
        "limit": 5
      }'
    ```
  </Accordion>

  <Accordion title="Boolean keyword operators (query_syntax: boolean)">
    For precise keyword search, set `search.query_syntax: "boolean"` to turn the
    query into a boolean expression: a space means **AND**, `|` means OR, `+`
    requires a term, `-` excludes a term, `"…"` matches an exact phrase, `*` matches
    a prefix, and `()` groups operators. Honored only with `search.mode: "lexical"`
    and the top-level recall `mode: "exact"`.

    ```bash 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 '{
        "search": {
          "query": "\"site reliability\" +kubernetes (golang | rust) -recruiter",
          "mode": "lexical",
          "query_syntax": "boolean"
        },
        "mode": "exact",
        "fields": ["fit", "basic_profile"],
        "limit": 5
      }'
    ```

    See the [Person Semantic Search guide](/guides/person-semantic-search#boolean-keyword-operators)
    for the full operator reference.
  </Accordion>

  <Accordion title="Concept search (semantic mode)">
    Use `semantic` to match the meaning of a query even when profiles use different
    words — vector similarity only.

    ```bash 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 '{
        "search": { "query": "people who scaled infrastructure at hypergrowth startups", "mode": "semantic" },
        "fields": ["fit", "basic_profile"],
        "limit": 5
      }'
    ```
  </Accordion>

  <Accordion title="Semantic ranking inside hard filters (mode: exact)">
    Enforce explicit `filters` as hard constraints, then rank inside that set with
    the query using the top-level `mode: "exact"`.

    ```bash 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 '{
        "search": { "query": "machine learning engineers who have built recommender systems", "mode": "hybrid" },
        "mode": "exact",
        "filters": { "field": "basic_profile.location.full_location", "type": "(.)", "value": "San Francisco" },
        "fields": ["fit", "basic_profile"],
        "limit": 5
      }'
    ```
  </Accordion>
</AccordionGroup>

***

## More recipes

Each recipe below is a full walkthrough with a tested request. Expand any one
to see the pattern, the response, and how the operators work.

<AccordionGroup>
  <Accordion title="Search by employer and title">
    This is the most common pattern for sales and recruiting: find people with a specific title at a specific company. This search finds VPs, Directors, and Heads of department at Retool.

    <CodeGroup>
      ```bash Request 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": {
            "op": "and",
            "conditions": [
              {
                "field": "experience.employment_details.company_name",
                "type": "in",
                "value": ["Retool"]
              },
              {
                "op": "or",
                "conditions": [
                  { "field": "experience.employment_details.current.title", "type": "(.)", "value": "VP" },
                  { "field": "experience.employment_details.current.title", "type": "(.)", "value": "Vice President" },
                  { "field": "experience.employment_details.current.title", "type": "(.)", "value": "Director" },
                  { "field": "experience.employment_details.current.title", "type": "(.)", "value": "Head of" },
                  { "field": "experience.employment_details.current.title", "type": "(.)", "value": "Head" }
                ]
              }
            ]
          },
          "limit": 1
        }'
      ```

      ```json Response theme={"theme":"vitesse-black"}
      {
          "profiles": [
              {
                  "crustdata_person_id": 97567,
                  "basic_profile": {
                      "name": "Krithika S.",
                      "headline": "Marketing at Thrive Capital",
                      "location": {
                          "country": "United States of America",
                          "raw": "United States"
                      }
                  },
                  "social_handles": {
                      "professional_network_identifier": {
                          "profile_url": "https://www.linkedin.com/in/krithix"
                      }
                  },
                  "experience": {
                      "employment_details": {
                          "current": [
                              {
                                  "name": "Thrive Capital",
                                  "title": "Executive in Residence, Marketing"
                              }
                          ],
                          "past": [
                              {
                                  "name": "Stripe",
                                  "title": "Head of Marketing"
                              },
                              { "name": "Retool", "title": "VP Marketing" },
                              { "name": "OpenAI", "title": "" },
                              { "name": "Google", "title": "" },
                              { "name": "Dropbox", "title": "" }
                          ]
                      }
                  }
              }
          ],
          "next_cursor": "H4sIAJO-oWkC_xXMMQ6DMAwAw...",
          "total_count": 88
      }
      ```
    </CodeGroup>

    <Note>Response trimmed for clarity.</Note>

    ### How the operators work

    There are two different operators at play here:

    * **`in`** on `experience.employment_details.company_name` checks if the person has worked at any of the listed companies (current or past). Pass an array even for a single company. To search only current employers, use `experience.employment_details.current.company_name` instead.
    * **`(.)`** on `experience.employment_details.title` does a regex match. The pipe `|` means "or", so `VP|Director|Head of` matches any title containing "VP", "Director", or "Head of". To search only current titles, use `experience.employment_details.current.title` instead.

    The `experience.employment_details.company_name` field includes **all** employers (current and past). If you see someone whose current role is at a different company, it means they previously worked at your target company.
  </Accordion>

  <Accordion title="Find people at a company by its profile URL">
    When you know a company's profile URL but not its exact name, filter on the employer's profile URL. Names can be ambiguous; the profile URL is exact, so this is the most reliable way to target one specific company.

    Lead with the current-employer field to find people who **currently** work there:

    <CodeGroup>
      ```bash Request — current employees 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.company_professional_network_profile_url",
            "type": "=",
            "value": "https://www.linkedin.com/company/stripe"
          },
          "limit": 1
        }'
      ```

      ```json Response theme={"theme":"vitesse-black"}
      {
          "profiles": [
              {
                  "basic_profile": {
                      "name": "Lucas Dickey",
                      "headline": "Day Zero Things"
                  },
                  "experience": {
                      "employment_details": {
                          "current": [{ "name": "Stripe", "title": "Builder" }]
                      }
                  }
              }
          ],
          "next_cursor": "H4sIABi5FmoC_xXMMQ7CMAwA...",
          "total_count": 11528
      }
      ```
    </CodeGroup>

    <Note>Response trimmed for clarity.</Note>

    <Warning>
      The value must be the **exact, full** profile URL — for example
      `https://www.linkedin.com/company/stripe`. A trailing slash
      (`.../stripe/`), a missing scheme (`linkedin.com/company/stripe`), or a
      bare slug (`stripe`) all return zero results.
    </Warning>

    ### Current, former, or either

    * **Current employees** — `experience.employment_details.current.company_professional_network_profile_url`
    * **Former employees** — `experience.employment_details.past.company_professional_network_profile_url`
    * **Anyone who has ever worked there** — combine both with an `or` group:

    ```json theme={"theme":"vitesse-black"}
    {
        "filters": {
            "op": "or",
            "conditions": [
                { "field": "experience.employment_details.current.company_professional_network_profile_url", "type": "=", "value": "https://www.linkedin.com/company/stripe" },
                { "field": "experience.employment_details.past.company_professional_network_profile_url", "type": "=", "value": "https://www.linkedin.com/company/stripe" }
            ]
        },
        "limit": 25
    }
    ```

    To target several companies at once, use the `in` operator with an array of profile URLs.

    <Note>
      The bare `experience.employment_details.company_professional_network_profile_url`
      path (all employers) is not filterable — use the `current.` or `past.`
      variants above. The accepted alias `...company_linkedin_profile_url`
      resolves to the same data.
    </Note>
  </Accordion>

  <Accordion title="Exclude specific titles">
    Sometimes you want everyone at a company *except* certain roles. Use the `not_in` operator to exclude titles.

    This search finds people at OpenAI or Retool but excludes interns and students.

    <CodeGroup>
      ```bash Request 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": {
            "op": "and",
            "conditions": [
              {
                "field": "experience.employment_details.company_name",
                "type": "in",
                "value": ["OpenAI", "Retool"]
              },
              {
                "field": "experience.employment_details.title",
                "type": "not_in",
                "value": ["Intern", "Student"]
              }
            ]
          },
          "limit": 2
        }'
      ```
    </CodeGroup>

    The `not_in` operator removes any profile where one of the listed values appears in their title history. This is useful for cleaning up results in recruiting or sales workflows.
  </Accordion>

  <Accordion title="Search within a geographic radius">
    The `geo_distance` filter finds people within a specific distance of a city. This is powerful for territory-based sales or local recruiting.

    This search finds CTOs within 10 miles of San Francisco.

    <CodeGroup>
      ```bash Request 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": {
            "op": "and",
            "conditions": [
              {
                "field": "professional_network.location.raw",
                "type": "geo_distance",
                "value": {
                  "location": "San Francisco",
                  "distance": 10,
                  "unit": "mi"
                }
              },
              {
                "field": "experience.employment_details.current.title",
                "type": "(.)",
                "value": "CTO|Chief Technology"
              }
            ]
          },
          "limit": 1
        }'
      ```

      ```json Response theme={"theme":"vitesse-black"}
      {
          "profiles": [
              {
                  "crustdata_person_id": 1188,
                  "basic_profile": {
                      "name": "Matthew Trentini",
                      "headline": "-",
                      "location": {
                          "city": "San Francisco",
                          "state": "California",
                          "country": "United States of America",
                          "raw": "San Francisco Bay Area"
                      }
                  },
                  "social_handles": {
                      "professional_network_identifier": {
                          "profile_url": "https://www.linkedin.com/in/matthew-trentini-b339bb5"
                      }
                  },
                  "experience": {
                      "employment_details": {
                          "current": [
                              {
                                  "name": "Farallon Capital Management",
                                  "title": "Chief Technology Officer"
                              }
                          ],
                          "past": [
                              {
                                  "name": "Farallon Capital Management",
                                  "title": "Lead Software Engineer"
                              }
                          ]
                      }
                  }
              }
          ],
          "next_cursor": "H4sIAJi-oWkC_xXMMQ7CMAxA0a...",
          "total_count": 104310
      }
      ```
    </CodeGroup>

    <Note>Response trimmed for clarity.</Note>

    ### How geo\_distance works

    The `geo_distance` filter uses the `professional_network.location.raw` field.
    The `value` is an object whose centre is given as **either** a `location`
    string (geocoded server-side) **or** an explicit `lat_lng` pair (which skips
    geocoding). If both are supplied, `lat_lng` wins.

    | Field      | Required | Description                                                                                  |
    | ---------- | -------- | -------------------------------------------------------------------------------------------- |
    | `location` | one of   | City or region name geocoded server-side (e.g., `"San Francisco"`, `"London"`, `"New York"`) |
    | `lat_lng`  | one of   | Explicit `[lat, lng]`. Lat in `[-90, 90]`, lng in `[-180, 180]`. Bypasses geocoding.         |
    | `distance` | Yes      | Radius from the centre point. Must be positive.                                              |
    | `unit`     | No       | One of `km`, `mi`, `miles`, `m`, `meters`, `ft`, `feet`. Defaults to `km`.                   |

    ### Search by explicit coordinates

    Use `lat_lng` when you already have coordinates (for example, from a map
    picker) or you want to skip the geocoding step. The example below finds
    people within 5 km of latitude `37.7749`, longitude `-122.4194` (downtown San
    Francisco).

    <CodeGroup>
      ```bash Request 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": "professional_network.location.raw",
            "type": "geo_distance",
            "value": {
              "lat_lng": [37.7749, -122.4194],
              "distance": 5,
              "unit": "km"
            }
          },
          "limit": 5
        }'
      ```
    </CodeGroup>
  </Accordion>

  <Accordion title="Exclude a geographic radius">
    The `geo_exclude` filter is the inverse of `geo_distance` — it removes people
    **inside** the radius and keeps everyone else. Use it to carve out a metro you
    already cover, or to find candidates outside a relocation zone.

    This search finds engineers in the United States who are **not** within 50 km of
    San Francisco.

    <CodeGroup>
      ```bash Request 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": {
            "op": "and",
            "conditions": [
              {
                "field": "professional_network.location.raw",
                "type": "geo_exclude",
                "value": {
                  "location": "San Francisco",
                  "distance": 50,
                  "unit": "km"
                }
              },
              {
                "field": "experience.employment_details.current.title",
                "type": "(.)",
                "value": "engineer"
              }
            ]
          },
          "limit": 1
        }'
      ```
    </CodeGroup>

    `geo_exclude` accepts the same value object as `geo_distance` (`location` or
    `lat_lng`, a required `distance`, and an optional `unit`), so you can also
    exclude a radius around explicit coordinates.
  </Accordion>

  <Accordion title="Exclude profiles matching a substring">
    Use `(!)` when you want to drop profiles whose value contains a particular
    phrase — useful when `not_in` is too rigid (it requires exact values) and
    you want a substring-style exclusion instead.

    This search finds VP-level people at Retool, then drops anyone whose
    headline mentions "Investor" or "Advisor".

    <CodeGroup>
      ```bash Request 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": {
            "op": "and",
            "conditions": [
              {
                "field": "experience.employment_details.current.company_name",
                "type": "=",
                "value": "Retool"
              },
              {
                "field": "experience.employment_details.current.title",
                "type": "(.)",
                "value": "VP"
              },
              {
                "field": "basic_profile.headline",
                "type": "(!)",
                "value": "Investor"
              },
              {
                "field": "basic_profile.headline",
                "type": "(!)",
                "value": "Advisor"
              }
            ]
          },
          "limit": 5
        }'
      ```
    </CodeGroup>

    <Note>
      `(!)` matches a multi-word value as a literal phrase. `(!) "New York"`
      excludes only profiles that literally contain `"New York"` — it does **not**
      exclude `"New Yorker"`. To exclude on each word independently, send a
      separate `(!)` condition for each word inside an `and` group, as shown
      above.
    </Note>
  </Accordion>

  <Accordion title="Search by country">
    For broader geographic targeting, filter by country directly.

    <Note>
      `basic_profile.location.country` uses full country names, such as `"United
                States"` or `"India"`.
    </Note>

    <CodeGroup>
      ```bash Request 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": "basic_profile.location.country",
            "type": "=",
            "value": "United States"
          },
          "limit": 2
        }'
      ```
    </CodeGroup>

    This returns all people located in the United States. With 125M+ matching profiles, you will want to combine this with title or employer filters to narrow results.
  </Accordion>

  <Accordion title="Search by employer headquarters country">
    Use `company_headquarters_country` when you want to filter by where a person's
    current or past employer is headquartered.

    <Note>
      Note: `company_headquarters_country` uses ISO-3 codes (`USA`, `IND`, `GBR`),
      unlike `basic_profile.location.country` which uses full names. Use ISO
      3166-1 alpha-3 codes for the current, past, and all-role headquarters
      country fields. See the [ISO 3166-1 alpha-3 country code
      list](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3) for accepted codes.
    </Note>

    This search finds founders or co-founders whose current employer is
    headquartered in the United States and who previously worked at an employer
    headquartered in India.

    <CodeGroup>
      ```bash Request 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": {
            "op": "and",
            "conditions": [
              {
                "op": "or",
                "conditions": [
                  {
                    "field": "experience.employment_details.current.title",
                    "type": "(.)",
                    "value": "Founder"
                  },
                  {
                    "field": "experience.employment_details.current.title",
                    "type": "(.)",
                    "value": "Co-Founder"
                  }
                ]
              },
              {
                "field": "experience.employment_details.current.company_headquarters_country",
                "type": "=",
                "value": "USA"
              },
              {
                "field": "experience.employment_details.past.company_headquarters_country",
                "type": "=",
                "value": "IND"
              }
            ]
          },
          "limit": 10
        }'
      ```
    </CodeGroup>
  </Accordion>

  <Accordion title="Exclude specific people from results">
    Use `post_processing` to remove known profiles from results. This is useful when re-running searches and you want to skip people you have already contacted.

    <CodeGroup>
      ```bash Exclude specific people 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"
          },
          "limit": 5,
          "post_processing": {
            "exclude_names": ["Ali Kashani"],
            "exclude_profiles": ["https://www.linkedin.com/in/alikashani"]
          }
        }'
      ```
    </CodeGroup>

    You can exclude by name, by profile URL, or both.
  </Accordion>

  <Accordion title="Build a profile card with company and school logos">
    Person Search returns stable Crustdata-hosted logo permalinks for employers (`company_profile_picture_permalink`) and schools (`institute_logo_permalink`), so you can render a profile card without resolving image URLs yourself. Request the `experience` and `education` sections for the person you want.

    <CodeGroup>
      ```bash Request 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": "crustdata_person_id", "type": "=", "value": 14540 },
          "fields": ["basic_profile", "experience", "education"],
          "limit": 1
        }'
      ```

      ```json Response theme={"theme":"vitesse-black"}
      {
          "profiles": [
              {
                  "crustdata_person_id": 14540,
                  "basic_profile": {
                      "name": "David Hsu",
                      "current_title": "Founder, CEO"
                  },
                  "experience": {
                      "employment_details": {
                          "current": [
                              {
                                  "name": "Retool",
                                  "title": "Founder, CEO",
                                  "company_profile_picture_permalink": "https://crustdata-media.s3.us-east-2.amazonaws.com/company/72f60d0ccad488216922fb784abc89890b49eeed8ab1eca1a0a12c72a68a0620.jpg"
                              }
                          ]
                      }
                  },
                  "education": {
                      "schools": [
                          {
                              "school": "University of Oxford",
                              "institute_logo_permalink": "https://crustdata-media.s3.us-east-2.amazonaws.com/company/3d2093a16f7cf7b459a0d30d4e795d0be5a41a3396f21dee899e43e8a8b6de8d.jpg"
                          }
                      ]
                  }
              }
          ],
          "next_cursor": "H4sIAFNsGWoC_xXM...",
          "total_count": 1
      }
      ```
    </CodeGroup>

    <Tip>
      `company_profile_picture_permalink` and `institute_logo_permalink` are
      returned for display only — they are not searchable fields.
    </Tip>
  </Accordion>

  <Accordion title="Find everyone at a company by its website domain">
    When you have a company's website domain but not its exact display name, filter on the employer's domain. Lead with the current-employer field to find people who **currently** work there.

    <CodeGroup>
      ```bash Request 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.company_website_domain",
            "type": "=",
            "value": "stripe.com"
          },
          "limit": 1
        }'
      ```

      ```json Response theme={"theme":"vitesse-black"}
      {
          "profiles": [
              {
                  "crustdata_person_id": 13183,
                  "basic_profile": {
                      "name": "Lucas Dickey",
                      "headline": "Day Zero Things",
                      "location": { "raw": "Greater Seattle Area", "country": "United States" }
                  },
                  "social_handles": {
                      "professional_network_identifier": {
                          "profile_url": "https://www.linkedin.com/in/lucasdickey"
                      }
                  },
                  "experience": {
                      "employment_details": {
                          "current": [
                              {
                                  "name": "Stripe",
                                  "title": "Builder",
                                  "company_website": "https://stripe.com"
                              }
                          ]
                      }
                  }
              }
          ],
          "next_cursor": "H4sIADnRQWoC_xXMOw...",
          "total_count": 11897
      }
      ```
    </CodeGroup>

    <Note>Response trimmed for clarity. The response carries the employer's full
    website URL under `company_website` — the `company_website_domain` paths are
    filter-side names and do not appear in search responses.</Note>

    To target several companies at once, switch to the `in` operator with an array of domains. For current employees use the `current.` field above; for former employees use `experience.employment_details.past.company_website_domain`; for anyone who has ever worked there, use the all-roles field `experience.employment_details.company_website_domain`.
  </Accordion>

  <Accordion title="Find people who recently changed jobs at a company">
    Combine the `recently_changed_jobs` flag with a current-employer filter to surface people who recently started at a target company — a strong signal for sales and recruiting outreach.

    <CodeGroup>
      ```bash Request 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": {
            "op": "and",
            "conditions": [
              {
                "field": "experience.employment_details.current.company_name",
                "type": "in",
                "value": ["OpenAI"]
              },
              { "field": "recently_changed_jobs", "type": "=", "value": true }
            ]
          },
          "limit": 1
        }'
      ```

      ```json Response theme={"theme":"vitesse-black"}
      {
          "profiles": [
              {
                  "crustdata_person_id": 13535,
                  "basic_profile": {
                      "name": "Gary Lin",
                      "headline": "Deployed at OpenAI (we’re hiring!)",
                      "location": { "raw": "New York, New York, United States" }
                  },
                  "experience": {
                      "employment_details": {
                          "current": [
                              { "name": "OpenAI", "title": "Member of Forward Deployed Staff" }
                          ]
                      }
                  }
              }
          ],
          "next_cursor": "H4sIADrRQWoC_xXMPQ...",
          "total_count": 1051
      }
      ```
    </CodeGroup>

    <Note>Response trimmed for clarity.</Note>

    `recently_changed_jobs` is a boolean — pair it with a `current.` employer or title filter to scope the signal to the population you care about. It is both filterable and sortable.
  </Accordion>

  <Accordion title="Exclude anyone who ever held a senior title">
    To find individual contributors only, use `not_in` on the **all-roles** career-history paths (`experience.employment_details.seniority_level` and `experience.employment_details.title`). On these all-employers fields, `not_in` drops anyone who has **ever** held that seniority or title at any point in their career — not just in their current role.

    <CodeGroup>
      ```bash Request 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": {
            "op": "and",
            "conditions": [
              {
                "field": "experience.employment_details.seniority_level",
                "type": "not_in",
                "value": ["Owner / Partner", "CXO", "Vice President", "Director"]
              },
              {
                "field": "experience.employment_details.title",
                "type": "not_in",
                "value": ["CEO", "President", "Chairman", "Founder", "Co-Founder"]
              },
              {
                "field": "experience.employment_details.current.title",
                "type": "(.)",
                "value": "engineer"
              }
            ]
          },
          "limit": 50
        }'
      ```
    </CodeGroup>

    This keeps people whose current title contains "engineer" but excludes anyone who has ever been a VP/Director/CXO or held a founder/CEO-level title. Because the exclusions are on the all-roles paths, a single past executive stint is enough to remove a profile.
  </Accordion>

  <Accordion title="Exclude people who ever worked at a competitor">
    Use `not_in` on the all-roles `experience.employment_details.company_name` path to remove anyone who has **ever** worked at a named company — current or past. This is the cleanest way to screen out competitor alumni from a candidate or prospect list.

    <CodeGroup>
      ```bash Request 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": {
            "op": "and",
            "conditions": [
              {
                "field": "experience.employment_details.current.title",
                "type": "(.)",
                "value": "Software Engineer"
              },
              {
                "field": "experience.employment_details.company_name",
                "type": "not_in",
                "value": ["Google", "Meta"]
              }
            ]
          },
          "limit": 50
        }'
      ```
    </CodeGroup>

    The all-roles `company_name` path covers current and past employers, so this excludes a profile if Google or Meta appears anywhere in their work history. For exact-company precision, prefer the company profile-URL paths (`...company_professional_network_profile_url`) over names.
  </Accordion>

  <Accordion title="VC sourcing: founders from top schools at new companies">
    Stack filters to source founders for an investor pipeline: a founder/CEO title, a target school, a recent current-role start date (a proxy for a recently founded company), and a country. Each layer narrows the universe.

    <CodeGroup>
      ```bash Request 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": {
            "op": "and",
            "conditions": [
              {
                "op": "or",
                "conditions": [
                  { "field": "experience.employment_details.current.title", "type": "(.)", "value": "Founder" },
                  { "field": "experience.employment_details.current.title", "type": "(.)", "value": "CEO" }
                ]
              },
              { "field": "education.schools.school", "type": "(.)", "value": "Stanford" },
              { "field": "experience.employment_details.current.start_date", "type": "=>", "value": "2023-01-01" },
              { "field": "basic_profile.location.country", "type": "=", "value": "United States" }
            ]
          },
          "limit": 1
        }'
      ```

      ```json Response theme={"theme":"vitesse-black"}
      {
          "profiles": [
              {
                  "crustdata_person_id": 1102,
                  "basic_profile": {
                      "name": "François Locoh-Donou",
                      "headline": "Chairman, President, & CEO of F5",
                      "location": { "raw": "Seattle, Washington, United States", "country": "United States" }
                  },
                  "education": {
                      "schools": [
                          { "school": "Stanford GSB", "degree": "Master of Business Administration (MBA)" }
                      ]
                  }
              }
          ],
          "next_cursor": "H4sIADvRQWoC_xXMMQ...",
          "total_count": 10046
      }
      ```
    </CodeGroup>

    <Note>Response trimmed for clarity. `basic_profile.location.country` uses full country names; `current.start_date` accepts ISO date strings with the `=>` (greater-than-or-equal) operator.</Note>
  </Accordion>

  <Accordion title="Cross-border talent: from one country's companies to another's">
    Filter on where a person's **past** and **current** employers are headquartered to find cross-border movers — for example, engineers who once worked at India-headquartered companies and are now at US-headquartered ones. Headquarters-country fields use ISO 3166-1 alpha-3 codes (`IND`, `USA`).

    <CodeGroup>
      ```bash Request 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": {
            "op": "and",
            "conditions": [
              { "field": "experience.employment_details.past.company_headquarters_country", "type": "=", "value": "IND" },
              { "field": "experience.employment_details.current.company_headquarters_country", "type": "=", "value": "USA" },
              { "field": "experience.employment_details.current.title", "type": "(.)", "value": "Engineer" }
            ]
          },
          "limit": 1
        }'
      ```

      ```json Response theme={"theme":"vitesse-black"}
      {
          "profiles": [
              {
                  "crustdata_person_id": 1394,
                  "basic_profile": {
                      "name": "Harbin Lee",
                      "location": { "raw": "Amsterdam, North Holland, Netherlands" }
                  },
                  "experience": {
                      "employment_details": {
                          "current": [
                              {
                                  "name": "OSIsoft, LLC.",
                                  "title": "Senior Software Engineer",
                                  "company_headquarters_country": "USA"
                              }
                          ],
                          "past": [
                              {
                                  "name": "InMobi",
                                  "title": "Senior Software Engineer",
                                  "company_headquarters_country": "IND"
                              }
                          ]
                      }
                  }
              }
          ],
          "next_cursor": "H4sIADzRQWoC_xXMMQ...",
          "total_count": 640192
      }
      ```
    </CodeGroup>

    <Note>Response trimmed for clarity. Note that the **person's** location and the **employer's** headquarters country are independent — this person is based in the Netherlands while their employers are US- and India-headquartered.</Note>
  </Accordion>

  <Accordion title="Filter by continent">
    For the broadest geographic targeting, filter on `basic_profile.location.continent`. It takes a full continent name such as `"Europe"`, `"Asia"`, or `"North America"`.

    <CodeGroup>
      ```bash Request 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": {
            "op": "and",
            "conditions": [
              { "field": "basic_profile.location.continent", "type": "=", "value": "Europe" },
              { "field": "experience.employment_details.current.title", "type": "(.)", "value": "Founder" }
            ]
          },
          "limit": 2
        }'
      ```
    </CodeGroup>

    This returns founders located anywhere in Europe (total\_count 1,055,157 at time of writing). Combine continent with title, employer, or country filters to narrow a large pool. `basic_profile.location.continent` is filterable but not sortable.
  </Accordion>

  <Accordion title="People who worked at two specific companies">
    To find people who worked at **both** of two named companies, target one as the current employer and the other as a past employer. Use the slot-specific paths `experience.employment_details.current.company_name` and `experience.employment_details.past.company_name`.

    <CodeGroup>
      ```bash Request 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": {
            "op": "and",
            "conditions": [
              { "field": "experience.employment_details.current.company_name", "type": "=", "value": "Stripe" },
              { "field": "experience.employment_details.past.company_name", "type": "=", "value": "Google" }
            ]
          },
          "limit": 1
        }'
      ```

      ```json Response theme={"theme":"vitesse-black"}
      {
          "profiles": [
              {
                  "crustdata_person_id": 153784,
                  "basic_profile": {
                      "name": "Vadim Jelezniakov",
                      "headline": "Head of Engineering for Data Infrastructure @ Stripe"
                  },
                  "experience": {
                      "employment_details": {
                          "current": [
                              { "name": "Stripe", "title": "Head of Data Infrastructure" }
                          ],
                          "past": [
                              { "name": "Meta", "title": "Director of Engineering, Core Services PE" },
                              { "name": "Google", "title": "" }
                          ]
                      }
                  }
              }
          ],
          "next_cursor": "H4sIADzRQWoC_xXMMQ...",
          "total_count": 754
      }
      ```
    </CodeGroup>

    <Note>Response trimmed for clarity.</Note>

    <Warning>
      This pattern works because each company is matched against a **different**
      employment slot (`current.` vs `past.`). Putting two different company names
      in two `=` conditions on the **same** all-roles path
      (`experience.employment_details.company_name`) returns zero results — a single
      employment record can't equal both names at once.
    </Warning>
  </Accordion>

  <Accordion title="Find people with a verified business email">
    Filter on `experience.employment_details.current.business_email_verified` to keep only profiles where a business email on the current role has been verified — useful when you plan to enrich and reach out by email.

    <CodeGroup>
      ```bash Request 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": {
            "op": "and",
            "conditions": [
              { "field": "experience.employment_details.current.business_email_verified", "type": "=", "value": true },
              { "field": "experience.employment_details.current.company_name", "type": "in", "value": ["Stripe"] }
            ]
          },
          "limit": 1
        }'
      ```

      ```json Response theme={"theme":"vitesse-black"}
      {
          "profiles": [
              {
                  "crustdata_person_id": 44532,
                  "basic_profile": {
                      "name": "Maureen Aguilar",
                      "headline": "Co-Founder at Stripe",
                      "location": { "raw": "White Post, Virginia, United States" }
                  },
                  "experience": {
                      "employment_details": {
                          "current": [
                              {
                                  "name": "Stripe",
                                  "title": "Co-Founder",
                                  "business_email_verified": true
                              }
                          ]
                      }
                  }
              }
          ],
          "next_cursor": "H4sIAD3RQWoC_xXMSw...",
          "total_count": 2858
      }
      ```
    </CodeGroup>

    <Note>Response trimmed for clarity. `business_email_verified` is filterable on the current, past, and all-roles paths but is not returned in standard search results — retrieve the actual email with [Contact Enrich](/person-docs/contact/enrich).</Note>
  </Accordion>

  <Accordion title="Sort a company's people by follower count">
    Add a `sorts` array to order results. This finds everyone associated with Retool and ranks them by professional-network followers, highest first. Request the fields you want to read alongside the sort key.

    <CodeGroup>
      ```bash Request 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"]
          },
          "sorts": [{ "field": "professional_network.followers", "order": "desc" }],
          "limit": 3,
          "fields": ["crustdata_person_id", "basic_profile.name"]
        }'
      ```

      ```json Response theme={"theme":"vitesse-black"}
      {
          "profiles": [
              { "crustdata_person_id": 193594, "basic_profile": { "name": "Jeff An" } },
              { "crustdata_person_id": 3408565, "basic_profile": { "name": "Jake Fox (on leave)" } },
              { "crustdata_person_id": 1061161, "basic_profile": { "name": "Cailen DSa" } }
          ],
          "next_cursor": "H4sIAL8XRmoC_x...",
          "total_count": 952
      }
      ```
    </CodeGroup>

    <Note>Response trimmed for clarity.</Note>

    `professional_network.followers` is filterable and sortable, but it is **not returned** in results — the sort ranks profiles by follower count without exposing the count itself. Always include a `sorts` array when paginating so ordering stays stable across pages — see [Pagination and sorting](/person-docs/search/reference#paginate-through-results).
  </Accordion>

  <Accordion title="Preview a search before running it in full">
    Preview mode returns lightweight results so you can sanity-check a filter and read `total_count` before committing to a full search. Set `preview: true` alongside your normal filters.

    <Note>
      Preview is a premium feature. To enable it for your account, reach out to
      [gtm@crustdata.co](mailto:gtm@crustdata.co). If preview is not enabled, the
      API returns `400 invalid_request` with the message `PersonDB preview feature
                is not available for your account.`
    </Note>

    <CodeGroup>
      ```bash Request 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": 1
        }'
      ```

      ```json Response theme={"theme":"vitesse-black"}
      {
        "profiles": [
          {
            "basic_profile": {
              "headline": "CEO & Co-Founder, Noise (Hiring at all levels)",
              "location": {
                "raw": "Gurgaon, Haryana, India"
              },
              "name": "Gaurav Khatri",
              "professional_network_name": "Gaurav Khatri",
              "profile_picture_permalink": "https://crustdata-media.s3.us-east-2.amazonaws.com/person/1cf520715028fad9e20ae5a7dfda3a45cd5eaec540e944f873ce7d02e22316cb.jpg"
            },
            "crustdata_person_id": 958,
            "social_handles": {
              "dev_platform_identifier": {
                "profile_url": null
              },
              "professional_network_identifier": {
                "profile_url": "https://www.linkedin.com/in/gauravkhatrigonoise"
              }
            }
          }
        ],
        "next_cursor": "H4sIAHyEXmoC_xXMMQ6DMAxA0asgzx3i2CSkV6kq5DiOGKpGhTBUiLuXjv8N_4DPbut3XmRb4D5AThktc1R0rqBjRKU8GYfiiYtXKYEkUBWKtapZ8sYUU6nRVSVhuA2wtbVfr0cap-eVvXV5zdr291_HFNB7Pn_nuKkBeQAAAA==",
        "total_count": 5961224,
        "total_count_relation": null
      }
      ```
    </CodeGroup>

    <Note>Response trimmed for clarity.</Note>

    Preview responses keep the same top-level shape as a normal search — `profiles`, `next_cursor`, and `total_count` — but each profile carries a reduced field set. See [Preview mode](/person-docs/search/reference#preview-mode) in the search reference.
  </Accordion>
</AccordionGroup>

***

## What to do next

* **Try more filter patterns** — see the [example requests](#example-requests) above for employer + title, geo radius, and exclude patterns.
* **Paginate and sort** — see [Pagination and sorting](/person-docs/search/reference#paginate-through-results) to walk through every matching profile in a stable order.
* **Look up operators and fields** — see [Search reference](/person-docs/search/reference) for operators, searchable fields, response fields, request parameters, and errors.
* **Enrich a profile** — once you have a profile URL from search, use [Person Enrich](/person-docs/enrichment/introduction) to get the full cached profile.
* **Discover filter values** — use [Person Autocomplete](/person-docs/autocomplete/introduction) to find exact indexed values for search filters before building a filter.
* **Check the API reference** — see the [OpenAPI spec](/openapi-specs/2025-11-01/introduction) for the full schema.