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

Ranked person lookup. Matches name, title, company, and location; 1-3 word queries boost the name field. Returns the top matches (up to 50), not every substring hit. Use keywords for exhaustive profile-text search.

​
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, references, offers, team_connections (related_people is a deprecated alias for references in the older shape). 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, compensation and offers require compensation:read, and team_connections requires connections:read.

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

Substring search across profile text. For looking up a specific person by name, use name instead.

​
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).

​
rejection_reason_ids_included
string<uuid>[]

Include persons whose current rejection stage has one of these rejection reasons. Get reason IDs from the rejection reasons configured for your team.

​
rejection_reason_ids_excluded
string<uuid>[]

Exclude persons whose current rejection stage has one of these rejection reasons.

​
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"). Get type keys from GET /v1/person-activities/types. Combine with activity_owner_ids_* and activity_date_* to require one activity that matches all of them, e.g. a given type in the last 7 days.

​
activity_types_excluded
string[]

Exclude persons with activities of these types. When activity owner or date filters are set, only activities by those owners or in that window count, so activity_types_excluded=["call"] with activity_date_type=within_last, activity_date_value=30, activity_date_unit=days returns persons with no call in the last 30 days.

​
activity_owner_ids_included
string<uuid>[]

Only count activities logged by these team members. Get IDs from GET /v1/team-members. Activity type, owner and date filters apply to the same activity, so combined with activity_types_included this returns persons with an activity of that type logged by one of these team members. Set on its own to return persons with any activity logged by these team members.

​
activity_owner_ids_excluded
string<uuid>[]

Ignore activities logged by these team members when matching the other activity filters.

​
activity_date_type
enum<string>

Only count activities that happened in a date window. within_last uses activity_date_value and activity_date_unit (e.g. the last 7 days); custom_range uses activity_date_start_date and/or activity_date_end_date. Applies to the same activity as the activity type and owner filters. Set on its own to return persons with any activity in the window.

Available options:
within_last,
custom_range
​
activity_date_value
integer

Length of the within_last window, e.g. 7 with activity_date_unit=days for the past week.

Example:

7

​
activity_date_unit
enum<string>

Time unit for activity_date_value.

Available options:
days,
weeks,
months,
years
​
activity_date_start_date
string

Earliest activity date for custom_range (ISO 8601, inclusive).

Example:

"2026-09-01T00:00:00Z"

​
activity_date_end_date
string

Latest activity date for custom_range (ISO 8601, inclusive).

Example:

"2026-09-30T23:59:59Z"

​
activity_content_keywords
string[]

Filter by keywords found in notes and document text. API keys also need notes:read and documents:read; requests without both scopes are rejected.

​
document_types
string[]

Include persons with documents of any of these type keys. Omit this and has_any_document to ignore documents.

​
has_any_document
boolean

When true, include only persons with at least one document. This also applies when document_types is provided.

​
off_limits
enum<string>

Controls off-limits persons: all keeps everyone, hide excludes them, and show returns only them.

Available options:
all,
hide,
show
​
off_limits_sources
enum<string>[]

Choose which Do Not Contact statuses count as off-limits: person, company, or both. Defaults to both.

Minimum array length: 1
Available options:
person,
company
​
known_by_team_member_ids
string<uuid>[]

Include only persons known by at least one of these team members, from their uploaded LinkedIn connections. Get IDs from GET /v1/team-members. Former team members can be picked here. API keys need the connections:read scope.

​
known_by_any_team_member
boolean

When true, include only persons known by at least one current team member. Ignored when known_by_team_member_ids is set. API keys need the connections:read scope.

​
min_connection_strength
enum<string>

Include only persons whose connection to a team member is at least this strong. Combines with known_by_team_member_ids; on its own it means any current team member. API keys need the connections:read scope.

Available options:
low,
medium,
high
​
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. Invalid when combined with only_client_contacts=true.

​
only_client_contacts
boolean

When true, return only persons who are client contacts (have a non-deleted client_contacts row for this team). Invalid when combined with hide_client_contacts=true.

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

​
company_attribute_filters
object[]

Filter by multi-company custom fields. Get attribute_id from GET /v1/custom-fields/persons, company IDs from POST /v1/companies/search.

​
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