Sign in

v1

latestOpenAPI 3.1.02026-07-261770816.7 KB
Approval Flows

Update approval flow

Toggle whether an existing approval flow is sequential (approver groups resolve one at a time in sort_order) or parallel (all groups activate at once). The flow must be in pending status — once it is approved or rejected the request returns 422. To restructure the groups themselves use PUT /v3/approval_flows/{id}/replace_approver_groups; to swap one user within a group use PUT /v3/approver_groups/{id}/replace_approver.

patch/v3/approval_flows/{id}

Path parameters

idinteger required

Request body

sequentialboolean

When true, approver groups resolve one at a time in sort_order; when false, all groups are activated in parallel. The flow must be pending; switching this on a started sequential flow re-evaluates which approvers are currently due.

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.