You are viewing the documentation of the new API versions. We would love to hear from you. You can write to use at support@crustdata.co for feedback and clarifications.
Worked examples for Person Search: employer + title, excludes, geographic radius, country, and post-processing exclusions.
Worked examples for Person Search. 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. For the operator list,
field catalog, and validation rules, see
Search reference.
Replace YOUR_API_KEY in each example with your actual API key. All
requests require the x-api-version: 2025-11-01 header.
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.
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.
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:
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.
To target several companies at once, use the in operator with an array of profile URLs.
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.
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.
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.
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.
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.
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).
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”.
(!) 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.
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.
Use company_headquarters_country when you want to filter by where a person’s
current or past employer is headquartered.
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 for accepted codes.
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.
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.
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.
