GRgreenhouse
Candidates

Search candidates

Search candidates through Greenhouse's full-text candidate search index, returning the same candidate shape as GET /v3/candidates with richer pipeline filters (job, stage, recruiter, coordinator, source, candidate tag, prospect pool, etc.). Use this when you need to slice across many filter dimensions at once or combine free-text matching with structured filters; for simple lookups by id or foreign key, prefer the list endpoint.

get/v3/candidates/search

Request

  • Base URL
    https://harvest.greenhouse.io
  • URL
    https://harvest.greenhouse.io/v3/candidates/search
  • Auth
    • OAuth 2
      Authorization code: https://auth.greenhouse.io/authorize
      Client credentials
      Token URL: https://auth.greenhouse.io/token scopes: harvest:candidates:list
    • or HTTP bearer

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[]

Return only candidates with these person ids.

fieldsstring[]

Comma separated list of fields to return

searchstring

Free-text search term.

tagstring

Filter by candidate tag name. Resolved to tag ids in the caller's organization; unknown tag returns no results. Use candidate_tag_id if you already have the id.

job_idinteger

Return only candidates with an application on this job.

status'candidates' | 'prospects' | 'all'

Restrict to candidates, prospects, or both. all returns both. Defaults to all.

job_status'all' | 'open' | 'closed' | 'draft'

Filter by the lifecycle status of the candidate's job(s). all returns every status.

department_idinteger

Return only candidates whose job is in this department.

office_idinteger

Return only candidates whose job is in this office.

source_idinteger

Return only candidates attributed to this source.

recruiter_idinteger

Return only candidates whose job has this recruiter.

coordinator_idinteger

Return only candidates whose job has this coordinator.

hiring_manager_idinteger

Return only candidates whose job has this hiring manager.

stage_idinteger

Return only candidates currently in this interview stage (matches the stage on their active application).

stage_namestring[]

Return only candidates currently in one of these interview stage names (exact match, case sensitive). Use alongside stage_id when you want name-based filtering without an extra id lookup.

stage_status'rejected' | 'paused' | 'completed' | 'hired' | 'in_process'

Filter by the candidate's current stage outcome (e.g. still in process, hired, rejected).

candidate_tag_idinteger

Filter by a specific candidate tag id. Prefer this over tag when the id is known to skip the name lookup.

job_post_idinteger

Return only candidates who applied via this job post.

prospect_pool_idinteger

Return only prospects in this prospect pool.

privateboolean

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

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

Filter by last-activity timestamp. 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). Bounds are applied at day-level granularity in UTC; sub-day precision in the supplied timestamp is ignored. The range is always inclusive; gt/lt are accepted but applied identically to gte/lte.

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

Changes

No recorded changes to this operation across all 1 revision of this API.