Advanced person search
The primary tool for finding and filtering persons across the entire database. All filters are optional and combinable. Use this instead of list-persons for any filtered query.
Direct search fields: email (exact match), name (partial, case-insensitive), phone (tiered matching: exact → normalized → last-7-digits), linkedin_url (exact profile match), vector_search (AI semantic search, min 5 chars).
Filter categories: jobs & pipeline stages, job titles, departments, companies (current/past), activity types & content keywords, owners (person/candidate), source, lists, contact presence, engagement recency, date ranges, locations, and custom attributes (select, numeric, date, team member).
Custom field / tag filtering: To filter by person tags or select-type attributes (e.g. “banking” tag), use select_attribute_filters with attribute_id and values (tag UUIDs). To discover attribute IDs and tag option IDs, call GET /v1/custom-fields/persons first.
Sorting: Set sort_by to one of: name, created_at, updated_at, current_job_title, company, linkedin_location, date_of_last_engagement, person_owner, last_activity_type, contact_email, or custom_<attribute_id>. Job-context sort columns (require job_id or exactly 1 job in job_ids_included): pipeline_stage, stage_date, added_to_job_at, rating, rating_note, candidate_owner. Use sort_order (asc or desc, default desc).
Include control: The include body array controls which sections appear in each person record. Allowed values: work_experience, education_experience, certifications, candidates, custom_fields, activities, compensation, related_people, offers. When omitted, returns only base fields (id, name, emails, phones, current_job_title, etc.). Pass an empty array [] to explicitly request base fields only.
Job-scoped search: Pass job_id to scope results to candidates in a specific job. This enables job-context sort columns and automatically filters to persons in that job. Combine with include: ["candidates"] to get candidate-level fields (pipeline stage, sourced_by, etc.).
Authorizations
Authenticate with a Bearer token: API key, OAuth token, or session token.
Body
Records to skip for pagination. Defaults to 0.
x >= 0Max records to return (1–100). Defaults to 100.
1 <= x <= 100Sort column. Values: name, created_at, updated_at, current_job_title, company, linkedin_location, date_of_last_engagement, person_owner, last_activity_type, contact_email. Job-context columns (require job_id or single job_ids_included): pipeline_stage, stage_date, added_to_job_at, rating, rating_note, candidate_owner. Custom field sorting: custom_<attribute_id>. Defaults to created_at.
"created_at"
Sort direction. Defaults to desc (newest first).
asc, desc Filter by exact email address match.
Filter by name (partial, case-insensitive).
Filter by phone number. Tiered matching: exact → normalized → last-7-digits.
Filter by LinkedIn profile URL. Must be a valid LinkedIn profile URL (https://www.linkedin.com/in/...)
^https?:\/\/(?:[a-z]{2}\.)?(?:www\.)?linkedin\.com\/in\/[^?#\s]+\/?(?:[?#][^\s]*)?$AI semantic search query (min 5 chars). Searches profile text via vector embeddings.
5Sections to embed in each person record. Values: work_experience, education_experience, certifications, candidates, custom_fields, activities, compensation, related_people, offers. Omit for base fields only. Pass empty array [] for base fields explicitly.
work_experience, education_experience, certifications, candidates, custom_fields, activities, compensation, related_people, offers Full-text keyword search across profile data.
Single job UUID to scope results to candidates in this job. Enables job-context sort columns (pipeline_stage, stage_date, etc.). Get job IDs from POST /v1/jobs/search. For multi-job filtering, use job_ids_included.
Only include candidates from these jobs. Get IDs from POST /v1/jobs/search.
Exclude candidates from these jobs.
When true, only return persons who are candidates in at least one of job_ids_included.
Exclude candidates from archived jobs.
Include persons whose current_job_title partially matches any of these strings.
Exclude persons whose current_job_title matches any of these strings.
Include persons in jobs with these department UUIDs.
Exclude persons in jobs with these department UUIDs.
Include persons currently at these companies. Get IDs from GET /v1/companies.
Exclude persons currently at these companies.
Include persons who previously worked at these companies.
Exclude persons who previously worked at these companies.
Include persons currently in these pipeline stages. Get stage IDs from GET /v1/jobs/{id} → pipeline_stages.
Exclude persons currently in these pipeline stages.
Include persons who were ever in these stages (historical).
Exclude persons who were ever in these stages (historical).
Filter by current pipeline stage within a specific job context. Stage IDs from GET /v1/jobs/{id} → pipeline_stages.
Exclude these pipeline stages within a specific job context.
Include persons with activities of these types (e.g. "email", "secondary_note").
Exclude persons with activities of these types.
Filter by keywords found in activity content text.
Include persons owned by these team members. Get IDs from GET /v1/team-members.
Exclude persons owned by these team members.
Include persons whose candidate record is owned by these team members.
Exclude persons whose candidate record is owned by these team members.
Filter by team members who sourced the candidate. Get IDs from GET /v1/team-members.
When true, also include candidates with no source assigned.
Include persons in these saved lists.
Exclude persons in these saved lists.
When true, exclude persons who are client contacts.
"has_email" returns only persons with at least one email; "missing_email" returns only persons with no email.
has_email, missing_email Engagement recency filter type.
engaged_within, not_engaged_within, custom_range, never_engaged Numeric value for engagement window (e.g. 30 for "30 days").
Time unit for engagement_value.
days, months, years Start of custom engagement date range (ISO 8601).
End of custom engagement date range (ISO 8601).
Only include candidates added to a job after this date (ISO 8601).
Only include candidates added to a job before this date (ISO 8601).
Include persons within these geographic bounding boxes.
Exclude persons within these geographic bounding boxes.
Filter by select/multi-select custom fields. Get attribute_id and tag IDs from GET /v1/custom-fields/persons.
Filter by numeric custom fields (min/max range). Get attribute_id from GET /v1/custom-fields/persons.
Filter by date custom fields (date range). Get attribute_id from GET /v1/custom-fields/persons.
Filter by team-member custom fields. Get attribute_id from GET /v1/custom-fields/persons, team member IDs from GET /v1/team-members.
Filter by company-level custom attributes on the person's current employer. Get attribute_id from GET /v1/custom-fields/companies.