Sign in

v1

latestOpenAPI 3.1.02026-07-261770816.7 KB
Users

List users

Users are the Greenhouse accounts inside your organization — recruiters, hiring managers, interviewers, coordinators, sourcers, and site admins. Each user has a primary_email (sign-in identifier), an optional partner-supplied employee_id for HRIS linkage, an activation state (deactivated), and a site_admin flag indicating unrestricted organization-level access. Use employee_ids, primary_email, or external_office_id/external_department_id to look up users by external identifiers without an extra id round-trip. Integration system users (ISUs) and other service accounts are hidden by default — pass show_service_accounts=true to include them.

get/v3/users

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

Return only users belonging to one of these recruiting Agency ids. Greenhouse stores agencies as separate records from users — fetch ids via GET /v3/agencies. Users without an agency association will not match.

office_idsinteger[]

Comma separated list

department_idsinteger[]

Comma separated list

linked_candidate_idsinteger[]

Return only users who are linked to one of these candidate ids via a person link (used when a candidate also exists as a Greenhouse user, e.g. an ex-employee re-entering the funnel). Look up the candidate id via GET /v3/candidates.

interviewer_tag_idsinteger[]

Return only users who have one of these interviewer Tag ids assigned. Interviewer tags are used to group users into interview panels — resolve ids via the tags endpoint.

fieldsstring[]

Comma separated list of fields to return

employee_idsstring[]

Return only users whose employee_id is in this list. Useful for HRIS-driven sync where the partner only has external employee identifiers.

custom_field_option_idinteger

Return only users whose user-attribute custom field value selects this custom_field_option id.

deactivatedboolean

Filter by activation state. true returns only deactivated users; false returns only active users; omit to return both.

primary_emailstring

Return only the user whose primary_email matches this address (exact match).

external_office_idstring

Return only users assigned to the office whose external_id matches this value. Use this when the partner only has external office identifiers; prefer office_id (via the parent filter) when the Greenhouse id is already known.

external_department_idstring

Return only users assigned to the department whose external_id matches this value. Use this when the partner only has external department identifiers; prefer department_id (via the parent filter) when the Greenhouse id is already known.

show_service_accountsboolean

If true, include integration/service-account users (used by Harvest integrations and ISUs) in the result set. Defaults to false, which omits them.

Response

Successful

idinteger
created_atstring date-time
updated_atstring date-time
first_namestring nullable
last_namestring nullable
primary_emailstring

Primary email address on the user's account. Sign-in identifier and the address Greenhouse uses for outbound mail; additional verified addresses are not surfaced here. Service accounts (integration/ISU users) have no email and are excluded from this endpoint by default; when included via show_service_accounts=true, their primary_email is an empty string.

job_titlestring nullable

Free-form job title set on the user's Greenhouse profile (e.g. Senior Recruiter). Not synchronized with any HRIS title.

agency_idinteger nullable

Id of the staffing agency this user belongs to, when the user is an external agency recruiter rather than an employee of your organization. null for in-house users.

namestring nullable

Concatenation of first_name and last_name rendered as a single display string. Provided for convenience; partners that need either component should read first_name/last_name directly.

deactivatedboolean

Whether the user has been deactivated. Deactivated users cannot sign in or be assigned to new jobs, but their historical activity (notes, scorecards, emails) is preserved. Toggle via POST /v3/users/{id}/deactivate and POST /v3/users/{id}/activate.

site_adminboolean

Whether the user holds the Site Admin role. Site admins have unrestricted access to every non-confidential job and to organization-level settings. Demote a site admin to a Basic user with POST /v3/users/{id}/revoke_permissions.

employee_idstring nullable

Partner-supplied external employee identifier, typically the user's HRIS or payroll id. Free-form string; not unique across organizations and null when no employee id has been set.

linked_candidate_idsinteger[]

Ids of candidate records linked to this user. Populated when an employee is represented by both a user record (for Greenhouse access) and a candidate record (for past or internal applications).

office_idsinteger[]

Ids of the offices this user is assigned to. Used to scope future job permissions and to filter the user list by office. Empty when the user is not pinned to any office.

department_idsinteger[]

Ids of the departments this user is assigned to. Used to scope future job permissions and to filter the user list by department. Empty when the user is not pinned to any department.

emailsstring[]

All email addresses on the user's account, including the primary address and any additional verified addresses.

custom_fieldsobject nullable