Sign in

v1

latestOpenAPI 3.1.02026-07-261770816.7 KB
Approval Flows

Create approval flow

Create a multi-step approval flow on a job (and optionally a specific offer), seeded with the supplied approver groups. Each job allows at most one flow per approval_type: one open_job flow gating job opening, one offer_job flow gating offer creation, and one offer_candidate prototype on the job plus one offer_candidate flow per offer (set offer_id for the latter). The new flow is created in pending status with no emails sent; call POST /v3/approval_flows/{id}/request_approvals to actually start it. Each approver entry may identify a user by user_id, email, or employee_id, but the same user cannot appear in more than one group of the same flow.

post/v3/approval_flows

Request body

job_idinteger required

Id of the job (hiring plan) this approval flow will gate. References a /v3/jobs row.

offer_idinteger

Id of the specific offer this approval flow will gate. Only valid (and required) when approval_type is offer_candidate; omit for open_job and offer_job flows.

approval_type'open_job' | 'offer_job' | 'offer_candidate' required

What this flow approves. open_job gates opening the job for recruiting, offer_job gates allowing offers to be created on the job, and offer_candidate gates extending an individual offer to a candidate. Each job allows at most one open_job and one offer_job flow; offer_candidate flows exist either as a job-level prototype (no offer_id) or one per offer.

sequentialboolean required

When true, approver groups resolve one at a time in submitted order — only after the current group resolves as approved are the next group's approvers asked. When false, all groups are activated in parallel once the flow is started.

Response

Successful

idinteger
created_atstring date-time
updated_atstring date-time
job_idinteger

Id of the job (hiring plan) this approval flow belongs to. References a /v3/jobs row.

offer_idinteger nullable

Id of the specific offer this approval flow gates. Set only for offer_candidate flows attached to a real offer; null on the open_job and offer_job flows (which gate the job itself), and null on the offer_candidate prototype flow that lives on the job before any offer is created.

approval_type'open_job' | 'offer_job' | 'offer_candidate'

What this flow approves. open_job gates opening the job for recruiting, offer_job gates allowing offers to be created on the job, and offer_candidate gates extending an individual offer to a candidate (one flow per offer, plus a prototype on the job).

sequentialboolean

When true, approver groups resolve one at a time in sort_order — only after the current group resolves as approved are the next group's approvers asked. When false, all groups are activated in parallel as soon as the flow is started.

versioninteger

Monotonically increasing revision counter for this approval flow. Job approval flows increment when system fields (e.g., department, requisition id, openings) or custom fields marked as triggering re-approval change after the flow has started. Use this together with an approver's version_sent to tell whether a pending approver is responding to the current version or a stale request. Offer approval flows attached to a specific offer_id are always version 1.

requested_by_idinteger nullable

Id of the user who started the flow by requesting approvals (the V3 request_approvals endpoint, or the in-app "Request Approval" button). References a /v3/users row. Null until the flow has been started — approver groups exist but no emails have been sent.

approval_status'pending' | 'rejected' | 'approved' | 'null' nullable

Denormalized terminal state of the flow, computed from the underlying approvers. pending while any group is still unresolved, approved once every group has reached its approvals_required threshold, rejected once any group has accumulated enough rejections to be unrecoverable. Updates to sequential and replace_approver_groups are only allowed while pending.