v1

latestOpenAPI 3.1.02026-07-261770816.7 KB

Approval Flows

Replace approver groups

Wholesale-replace the ordered tiers of approvers on an existing approval flow — the V3 equivalent of rebuilding the flow's structure from an external HRIS. The flow must be in pending status; resolved (approved or rejected) flows cannot be modified. The new array's index becomes each group's sort_order, each approver entry must identify a user by user_id, email, or employee_id, and the same user cannot appear in more than one group. To swap a single approver inside a group without touching the rest of the flow use PUT /v3/approver_groups/{id}/replace_approver; to flip the flow between sequential and parallel use PATCH /v3/approval_flows/{id}.

put/v3/approval_flows/{id}/replace_approver_groups

Path parameters

idinteger required

Request body

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.