---
title: "List approval flows"
method: GET
path: "/v3/approval_flows"
tags: ["Approval Flows"]
---

# List approval flows

`GET /v3/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.

## Query parameters

- `cursor` string
- `per_page` integer
- `ids` integer[]
- `created_at` object
  - `gte` string, date-time
  - `lte` string, date-time
  - `gt` string, date-time
  - `lt` string, date-time
- `updated_at` object
  - `gte` string, date-time
  - `lte` string, date-time
  - `gt` string, date-time
  - `lt` string, date-time
- `job_ids` integer[]
- `offer_ids` integer[]
- `fields` string[]
- `approval_type` 'open_job' | 'offer_job' | 'offer_candidate'

## Response `200`

Successful

- object[]
  - `id` integer
  - `created_at` string, date-time
  - `updated_at` string, date-time
  - `job_id` integer — Id of the job (hiring plan) this approval flow belongs to. References a `/v3/jobs` row.
  - `offer_id` integer, 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).
  - `sequential` boolean — 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.
  - `version` integer — 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_id` integer, 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`.

---

[API](https://skmtc.dev/greenhouse/apis/auth-api.md) · [All operations](https://skmtc.dev/greenhouse/apis/auth-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/greenhouse/auth-api/revisions/9517a2e54640/schema)