Sign in

v1

latestOpenAPI 3.1.02026-07-261770816.7 KB
Approval Flows

List approval flows

Approval flows are the multi-step approval definitions attached to a job or to a candidate's offer. Each flow has an ordered list of approver groups (/v3/approver_groups?approval_flow_ids=), and each group holds the individual approvers (/v3/approvers?approver_group_ids=); a flow resolves as approved only when every group resolves as approved. Filter by approval_type to scope to job-opening, job-offer, or candidate-offer flows, and by job_ids or offer_ids to scope to specific parents. Default approval flows that serve as the prototype for new jobs are not returned here.

get/v3/approval_flows

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

Return only approval flows that gate these job (hiring plan) ids. Matches open_job and offer_job flows whose hiring_plan_id is in the list; offer_candidate flows are excluded since they hang off an offer rather than a job.

offer_idsinteger[]

Return only offer_candidate approval flows for these offer ids. Each offer has its own approver chain — distinct from the open_job/offer_job flows on the underlying job — so filter by offer_ids to fetch just the candidate-level offer approvals.

fieldsstring[]

Comma separated list of fields to return

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

Filter by the kind of approval the flow gates: open_job (opening the job), offer_job (allowing offers on the job), or offer_candidate (extending an individual offer).

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.