Sign in

v1

latestOpenAPI 3.1.02026-07-261770816.7 KB
Candidate Employments

List candidate employments

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.

get/v3/candidate_employments

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

Comma separated list

fieldsstring[]

Comma separated list of fields to return

latestboolean

When true, return only each candidate's most recent employment entry; when false, exclude the most recent. Omit to include the full work history.

Response

Successful

idinteger
created_atstring date-time
updated_atstring date-time
candidate_idinteger

Id of the candidate (person) this employment entry belongs to.

company_namestring

Free-text name of the employer, as entered on the candidate's profile.

titlestring

Free-text job title held at this employer.

start_datestring date

Start date of this employment, as an ISO 8601 date. The Greenhouse UI displays only the month and year.

end_datestring 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.

latestboolean 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.