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

> Worked examples for Person Search: employer + title, excludes, geographic radius, country, and post-processing exclusions.

Worked examples for [Person Search](/person-docs/search/introduction). Each
example is a full working request you can copy, paste, and adapt.

For the core walkthrough (first search, combining filters with `and`), see
[Person Search](/person-docs/search/introduction). For the operator list,
field catalog, and validation rules, see
[Search reference](/person-docs/search/reference).

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

***

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

***

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

***

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

***

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

***

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

***

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

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

***

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

***

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

***

## Next steps

* [Pagination and sorting](/person-docs/search/reference#paginate-through-results) — walk through every matching profile in a stable order.
* [Search reference](/person-docs/search/reference) — operators, searchable fields, response fields, request parameters, and errors.
* [Person Autocomplete](/person-docs/autocomplete/introduction) — discover valid indexed values before building a filter.