---
title: "List candidate employments"
method: GET
path: "/v3/candidate_employments"
tags: ["Candidate Employments"]
---

# List candidate employments

`GET /v3/candidate_employments`

## Request

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

Candidate employments are the work history entries on a candidate's profile — one row per employer/title the candidate has held. V3 flattens what V1 nested under `/v1/candidates/{id}/employments`; filter with `candidate_ids` to retrieve a single candidate's full work history. `company_name` and `title` are free-text strings (unlike candidate educations, they are not backed by custom-field option ids). Use `latest=true` to retrieve only each candidate's most recent employment, which mirrors the `company` and `title` shown on the parent candidate record.

## 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
- `candidate_ids` integer[]
- `fields` string[]
- `latest` boolean

## Response `200`

Successful

- object[]
  - `id` integer
  - `created_at` string, date-time
  - `updated_at` string, date-time
  - `candidate_id` integer: Id of the candidate (person) this employment entry belongs to.
  - `company_name` string: Free-text name of the employer, as entered on the candidate's profile.
  - `title` string: Free-text job title held at this employer.
  - `start_date` string, date: Start date of this employment, as an ISO 8601 date. The Greenhouse UI displays only the month and year.
  - `end_date` string, date, nullable: End date of this employment, as an ISO 8601 date. `null` indicates the employment is current (ongoing). The Greenhouse UI displays only the month and year.
  - `latest` boolean, nullable: `true` when this is the candidate's most recent employment. Greenhouse maintains this flag automatically — the current job (`end_date: null`) wins, otherwise the entry with the latest `end_date` — and at most one employment per candidate has `latest: true`. Mirrors the `company` and `title` shown on the parent candidate record.

---

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