---
title: "Search candidates"
method: GET
path: "/v3/candidates/search"
tags: ["Candidates"]
---

# Search candidates

`GET /v3/candidates/search`

## Request

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

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.

## Query parameters

- `cursor` string
- `per_page` integer
- `ids` integer[]
- `fields` string[]
- `search` string
- `tag` string
- `job_id` integer
- `status` 'candidates' | 'prospects' | 'all'
- `job_status` 'all' | 'open' | 'closed' | 'draft'
- `department_id` integer
- `office_id` integer
- `source_id` integer
- `recruiter_id` integer
- `coordinator_id` integer
- `hiring_manager_id` integer
- `stage_id` integer
- `stage_name` string[]
- `stage_status` 'rejected' | 'paused' | 'completed' | 'hired' | 'in_process'
- `candidate_tag_id` integer
- `job_post_id` integer
- `prospect_pool_id` integer
- `private` boolean
- `last_activity_at` object
  - `gte` string, date-time
  - `lte` string, date-time
  - `gt` string, date-time
  - `lt` string, date-time

## Response `200`

Successful

- object[]
  - `id` integer
  - `created_at` string, date-time
  - `updated_at` string, date-time
  - `first_name` string, nullable
  - `last_name` string, nullable
  - `preferred_name` string, nullable: Preferred or chosen name the candidate goes by, when different from their legal first name.
  - `company` string, nullable: Candidate's current company, as entered on their profile.
  - `title` string, nullable: Candidate's current job title, as entered on their profile.
  - `last_activity_at` string, date-time, nullable: Timestamp of the most recent activity on any of the candidate's applications (notes, emails, stage changes, etc.), in ISO 8601.
  - `private` boolean, nullable: If true, the candidate is restricted to users with `View Private Candidates` access. Defaults to `false`.
  - `can_email` boolean: Whether this candidate has consented to receive email communication from your organization.
  - `time_zone` string, nullable: Candidate's time zone as a Rails-style identifier (for example `Eastern Time (US & Canada)`).
  - `tags` string[]: Candidate tag names applied to this candidate within your organization.
  - `linked_user_ids` integer[]: Ids of Greenhouse users linked to this candidate (employees represented by both a user record and a candidate record).
  - `phone_numbers` object[]: Phone numbers on the candidate's profile. Each entry pairs the `value` with a `type` such as `mobile`, `home`, `work`, `skype`, or `other`. Ordered by type — `home`, `work`, `mobile`, `skype`, then `other` — and oldest first within a type.
    - `value` string
    - `type` string
  - `addresses` object[]: Postal addresses on the candidate's profile. Each entry pairs the `value` with a `type` such as `home`, `work`, or `other`. Ordered oldest first.
    - `value` string
    - `type` string
  - `email_addresses` object[]: Email addresses on the candidate's profile. Each entry pairs the `value` with a `type` such as `personal`, `work`, or `other`. Ordered by most recently updated, and oldest first among entries last updated at the same time.
    - `value` string
    - `type` string
  - `website_addresses` object[]: Personal websites or portfolio URLs on the candidate's profile. Each entry pairs the `value` with a `type` such as `personal`, `company`, `portfolio`, `blog`, or `other`. Ordered oldest first.
    - `value` string
    - `type` string
  - `social_media_addresses` object[]: Social media handles or URLs on the candidate's profile. Social entries are untyped — only the `value` is returned. Ordered oldest first.
    - `value` string
  - `custom_fields` object, nullable

---

[API](https://skmtc.dev/greenhouse/apis/harvest-api.md) - [All operations](https://skmtc.dev/greenhouse/apis/harvest-api/llms.txt) - [OpenAPI document](https://skmtc.dev/greenhouse/apis/harvest-api/revisions/822822e3f771?raw)