Recruitment

Openings and the people applying to them. Candidates are not employees and their records carry personal contact details, which is why they sit behind their own scope. CVs are not exposed.

Plan feature

These endpoints need a plan that includes Recruitment (recruitment). On a plan without it, requests return 402 with code: plan_upgrade_required and feature naming what an upgrade would add.

List job openings

GET/v1/job_openings

Query parameters

Name	Type	Required	Description
limit	integer	No	Page size. Values above 100 are clamped.
starting_after	string	No	Opaque cursor from a previous response’s next_cursor.
updated_since	timestamp	No	Return records changed at or after this instant. Tracks the record itself, not its child collections.
status	string	No	Only openings in this state.
department_id	string	No	Only openings in this department.
branch_id	string	No	Only openings at this branch.

Responses

Status	Meaning
200	A page of job openings.
401	The API key is missing, malformed, revoked or expired.
402	The workspace's plan does not include Recruitment (plan_upgrade_required).
403	The key does not carry the required scopes.
429	Rate limit exceeded. See the RateLimit-* headers.

Retrieve a job opening

GET/v1/job_openings/{id}

Path parameters

Name	Type	Required	Description
id	string	Yes	The identifier returned as id on the object.

Responses

Status	Meaning
200	The job opening.
401	The API key is missing, malformed, revoked or expired.
402	The workspace's plan does not include Recruitment (plan_upgrade_required).
403	The key does not carry the required scopes.
404	No such job opening in this workspace.
429	Rate limit exceeded. See the RateLimit-* headers.

List candidates

GET/v1/candidates

Query parameters

Name	Type	Required	Description
limit	integer	No	Page size. Values above 100 are clamped.
starting_after	string	No	Opaque cursor from a previous response’s next_cursor.
updated_since	timestamp	No	Return records changed at or after this instant. Tracks the record itself, not its child collections.
email	string	No	Look up a candidate by email.

Responses

Status	Meaning
200	A page of candidates.
401	The API key is missing, malformed, revoked or expired.
402	The workspace's plan does not include Recruitment (plan_upgrade_required).
403	The key does not carry the required scopes.
429	Rate limit exceeded. See the RateLimit-* headers.

Retrieve a candidate

GET/v1/candidates/{id}

Path parameters

Name	Type	Required	Description
id	string	Yes	The identifier returned as id on the object.

Responses

Status	Meaning
200	The candidate.
401	The API key is missing, malformed, revoked or expired.
402	The workspace's plan does not include Recruitment (plan_upgrade_required).
403	The key does not carry the required scopes.
404	No such candidate in this workspace.
429	Rate limit exceeded. See the RateLimit-* headers.

List applications

GET/v1/applications

Query parameters

Name	Type	Required	Description
limit	integer	No	Page size. Values above 100 are clamped.
starting_after	string	No	Opaque cursor from a previous response’s next_cursor.
updated_since	timestamp	No	Return records changed at or after this instant. Tracks the record itself, not its child collections.
candidate_id	string	No	Only this candidate’s applications.
job_opening_id	string	No	Only applications to this opening.
stage	string	No	Only applications at this stage.
source	string	No	Only applications from this source.

Responses

Status	Meaning
200	A page of applications.
401	The API key is missing, malformed, revoked or expired.
402	The workspace's plan does not include Recruitment (plan_upgrade_required).
403	The key does not carry the required scopes.
429	Rate limit exceeded. See the RateLimit-* headers.

Retrieve an application

GET/v1/applications/{id}

Path parameters

Name	Type	Required	Description
id	string	Yes	The identifier returned as id on the object.

Responses

Status	Meaning
200	The application.
401	The API key is missing, malformed, revoked or expired.
402	The workspace's plan does not include Recruitment (plan_upgrade_required).
403	The key does not carry the required scopes.
404	No such application in this workspace.
429	Rate limit exceeded. See the RateLimit-* headers.