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

# List candidates

`GET /v3/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.

## Query parameters

- `cursor` string
- `per_page` integer
- `ids` integer[]
- `created_at` object
  - `gte` string, date-time
  - `lte` string, date-time
  - `gt` string, date-time
  - `lt` string, date-time
- `updated_at` object
  - `gte` string, date-time
  - `lte` string, date-time
  - `gt` string, date-time
  - `lt` string, date-time
- `fields` string[]
- `last_activity_at` object
  - `gte` string, date-time
  - `lte` string, date-time
  - `gt` string, date-time
  - `lt` string, date-time
- `custom_field_option_id` integer
- `private` boolean
- `email` string
- `tag` string

## 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`.
    - `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`.
    - `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`.
    - `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`.
    - `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.
    - `value` string
  - `custom_fields` object, nullable

---

[API](https://skmtc.net/greenhouse/apis/auth-api.md) · [All operations](https://skmtc.net/greenhouse/apis/auth-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/greenhouse/auth-api/versions/9517a2e54640/schema)