Sign in

v1

latestOpenAPI 3.1.02026-07-261770816.7 KB
Candidates

List candidates

Candidates are the people your organization is recruiting — both active applicants and prospects. A candidate record holds the personal profile (names, contact methods, tags, custom fields) and is the parent of one or more applications, each of which represents the candidate's journey on a specific job. Use the ids query parameter to fetch a single candidate by id; nested data (applications, attachments, educations, employments) lives on its own resource endpoint in V3.

get/v3/candidates

Query parameters

cursorstring

Cursor link for pagination from previous page response header. Do not use any other parameters when using this.

per_pageinteger

Number of results per page

idsinteger[]

Comma separated list

gtestring date-time
ltestring date-time
gtstring date-time
ltstring date-time
gtestring date-time
ltestring date-time
gtstring date-time
ltstring date-time
fieldsstring[]

Comma separated list of fields to return

gtestring date-time
ltestring date-time
gtstring date-time
ltstring date-time

Filter by last-activity timestamp on the candidate's applications. Pass any combination of gte, lte, gt, lt as ISO-8601 date-times (e.g. last_activity_at[gte]=2026-01-01T00:00:00Z&last_activity_at[lte]=2026-04-01T00:00:00Z).

custom_field_option_idinteger

Return only candidates whose custom field value matches this single-select or multi-select option id.

privateboolean

Include private candidates the caller has access to. Defaults to true; set false to exclude private candidates.

emailstring

Return only candidates with this email address on their profile. Matches against any of the candidate's email addresses, case-insensitively.

tagstring

Filter by candidate tag name (exact match). Use the /v3/candidate_tags endpoint to discover available tag names for your organization.

Response

Successful

idinteger
created_atstring date-time
updated_atstring date-time
first_namestring nullable
last_namestring nullable
preferred_namestring nullable

Preferred or chosen name the candidate goes by, when different from their legal first name.

companystring nullable

Candidate's current company, as entered on their profile.

titlestring nullable

Candidate's current job title, as entered on their profile.

last_activity_atstring date-time nullable

Timestamp of the most recent activity on any of the candidate's applications (notes, emails, stage changes, etc.), in ISO 8601.

privateboolean nullable

If true, the candidate is restricted to users with View Private Candidates access. Defaults to false.

can_emailboolean

Whether this candidate has consented to receive email communication from your organization.

time_zonestring nullable

Candidate's time zone as a Rails-style identifier (for example Eastern Time (US & Canada)).

tagsstring[]

Candidate tag names applied to this candidate within your organization.

linked_user_idsinteger[]

Ids of Greenhouse users linked to this candidate (employees represented by both a user record and a candidate record).

custom_fieldsobject nullable