Skip to main content
POST
Advanced person search

Authorizations

​
Authorization
string
header
required

Authenticate with a Bearer token: API key, OAuth token, or session token.

Body

application/json
​
offset
integer
default:0

Records to skip for pagination. Defaults to 0.

Required range: x >= 0
​
limit
integer
default:100

Max records to return (1–100). Defaults to 100.

Required range: 1 <= x <= 100
​
sort_by
string

Sort column. Values: name, created_at, updated_at, current_job_title, company, 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.

Example:

"created_at"

​
sort_order
enum<string>
default:desc

Sort direction. Defaults to desc (newest first).

Available options:
asc,
desc
​
email
string<email>

Filter by exact email address match.

​
name
string

Filter by name (partial, case-insensitive).

​
phone
string

Filter by phone number. Tiered matching: exact → normalized → last-7-digits.

​
linkedin_url
string

Filter by LinkedIn profile URL. Must be a valid LinkedIn profile URL (https://www.linkedin.com/in/...)

Pattern: ^https?:\/\/(?:[a-z]{2}\.)?(?:www\.)?linkedin\.com\/in\/[^?#\s]+\/?(?:[?#][^\s]*)?$
​
vector_search
string

AI semantic search query (min 5 chars). Searches profile text via vector embeddings.

Minimum string length: 5
​
include
enum<string>[]

Sections 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. For API-key callers, unavailable requested sections are omitted: activities requires notes:read, candidates requires candidates:read, and compensation and offers require compensation:read.

Available options:
work_experience,
education_experience,
certifications,
candidates,
custom_fields,
activities,
compensation,
related_people,
offers
​
keywords
string[]

Full-text keyword search across profile data.

​
job_id
string<uuid>

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.

​
job_ids_included
string<uuid>[]

Only include candidates from these jobs. Get IDs from POST /v1/jobs/search.

​
job_ids_excluded
string<uuid>[]

Exclude candidates from these jobs.

​
filter_out_if_not_in_job
boolean

When true, only return persons who are candidates in at least one of job_ids_included.

​
exclude_archived_jobs
boolean
default:true

Exclude candidates from archived jobs. Defaults to true.

​
job_titles_included
string[]

Include persons whose current_job_title partially matches any of these strings.

​
job_titles_excluded
string[]

Exclude persons whose current_job_title matches any of these strings.

​
departments_included
string<uuid>[]

Include persons in jobs with these department UUIDs.

​
departments_excluded
string<uuid>[]

Exclude persons in jobs with these department UUIDs.

​
current_company_ids
string<uuid>[]

Include persons currently at these companies. Get IDs from GET /v1/companies.

​
current_company_ids_excluded
string<uuid>[]

Exclude persons currently at these companies.

​
past_company_ids
string<uuid>[]

Include persons who previously worked at these companies.

​
past_company_ids_excluded
string<uuid>[]

Exclude persons who previously worked at these companies.

​
pipeline_stage_ids_included
string<uuid>[]

Include persons currently in these pipeline stages. Get stage IDs from GET /v1/jobs/{id} → pipeline_stages.

​
pipeline_stage_ids_excluded
string<uuid>[]

Exclude persons currently in these pipeline stages.

​
pipeline_stage_history_included
string<uuid>[]

Include persons who were ever in these stages (historical).

​
pipeline_stage_history_excluded
string<uuid>[]

Exclude persons who were ever in these stages (historical).

​
job_page_pipeline_stages_in
string<uuid>[]

Filter by current pipeline stage within a specific job context. Stage IDs from GET /v1/jobs/{id} → pipeline_stages.

​
job_page_pipeline_stages_ex
string<uuid>[]

Exclude these pipeline stages within a specific job context.

​
activity_types_included
string[]

Include persons with activities of these types (e.g. "email", "secondary_note").

​
activity_types_excluded
string[]

Exclude persons with activities of these types.

​
activity_content_keywords
string[]

Filter by keywords found in activity content text.

​
person_owner_ids_included
string<uuid>[]

Include persons owned by these team members. Get IDs from GET /v1/team-members.

​
person_owner_ids_excluded
string<uuid>[]

Exclude persons owned by these team members.

​
candidate_owner_ids_included
string<uuid>[]

Include persons whose candidate record is owned by these team members.

​
candidate_owner_ids_excluded
string<uuid>[]

Exclude persons whose candidate record is owned by these team members.

​
sourced_by_ids
string<uuid>[]

Filter by team members who sourced the candidate. Get IDs from GET /v1/team-members.

​
sourced_by_include_empty
boolean

When true, also include candidates with no source assigned.

​
list_ids_included
string<uuid>[]

Include persons in these saved lists.

​
list_ids_excluded
string<uuid>[]

Exclude persons in these saved lists.

​
hide_client_contacts
boolean

When true, exclude persons who are client contacts.

​
contact_email_filter
enum<string>

"has_email" returns only persons with at least one email; "missing_email" returns only persons with no email.

Available options:
has_email,
missing_email
​
engagement_type
enum<string>

Engagement recency filter type.

Available options:
engaged_within,
not_engaged_within,
custom_range,
never_engaged
​
engagement_value
number

Numeric value for engagement window (e.g. 30 for "30 days").

​
engagement_unit
enum<string>

Time unit for engagement_value.

Available options:
days,
months,
years
​
engagement_start_date
string

Start of custom engagement date range (ISO 8601).

​
engagement_end_date
string

End of custom engagement date range (ISO 8601).

​
added_to_job_start_date
string

Only include candidates added to a job after this date (ISO 8601).

​
added_to_job_end_date
string

Only include candidates added to a job before this date (ISO 8601).

​
locations_included
object[]

Include persons within these geographic bounding boxes.

​
locations_excluded
object[]

Exclude persons within these geographic bounding boxes.

​
select_attribute_filters
object[]

Filter by select/multi-select custom fields. Get attribute_id and tag IDs from GET /v1/custom-fields/persons.

​
numeric_attribute_filters
object[]

Filter by numeric custom fields (min/max range). Get attribute_id from GET /v1/custom-fields/persons.

​
date_attribute_filters
object[]

Filter by date custom fields (date range). Get attribute_id from GET /v1/custom-fields/persons.

​
team_member_attribute_filters
object[]

Filter by team-member custom fields. Get attribute_id from GET /v1/custom-fields/persons, team member IDs from GET /v1/team-members.

​
created_at_gte
string

Only include persons created on or after this date (ISO 8601).

​
created_at_lte
string

Only include persons created on or before this date (ISO 8601).

​
updated_at_gte
string

Only include persons updated on or after this date (ISO 8601).

​
updated_at_lte
string

Only include persons updated on or before this date (ISO 8601).

​
current_company_attribute_filters
object

Filter by company-level custom attributes on the person's current employer. Get attribute_id from GET /v1/custom-fields/companies.

Response

Successful search response

​
success
enum<boolean>
required
Available options:
true
​
data
object[]
required
​
meta
object
required