--- title: "List approval requests" method: GET path: "/approvals" tags: ["Approvals (Beta)"] --- # List approval requests `GET /approvals` ## Request - Base URL: `https://api.fireblocks.io/v1` - URL: `https://api.fireblocks.io/v1/approvals` - Auth: none declared - TypeScript: (a function with typed inputs; its response is checked against the schema) Retrieve the pending approval requests the authenticated API user is eligible to act on, including requests the user has already approved that are still pending overall. The response is scoped to the authenticated user by default. Pass `userId` to read another user's queue, or `includeAllUsers=true` to read every pending request in the workspace. Both require an Admin, Non-Signing Admin, Security Admin or Security Auditor role and are rejected with 403 otherwise. Set `quorumStatusMode=SUMMARY` to include each request's approval thresholds and counts. The per-approver breakdown is available only when fetching a single request — see `GET /approvals/{requestId}`. Endpoint Permission: Owner, Admin, Non-Signing Admin, Approver, Signer, Security Admin, Security Auditor. ## Query parameters - `includeUserApproved` boolean - `userId` string - `includeAllUsers` boolean - `quorumStatusMode` 'NONE' | 'SUMMARY' - `pageSize` integer - `pageCursor` string ## Response `200` Approval requests the authenticated user is eligible to act on. - ListApprovalsResponse - `data` ApprovalRequestItem[], required: The approval requests the authenticated user is eligible to act on. - `requestPayload` string, required: The pending approval request as a JSON string, exactly as produced by the backend — this is the precise string to sign in order to approve the request (sign it as-is; do not re-serialize). The JSON has the shape { requestId, requestType, requestTimestamp (epoch ms), expiresAt (epoch seconds), requestData }, where requestData is the request-type-specific payload. - `requestSignature` string: Signature over the requestPayload. Empty until request signing is implemented. - `userStatus` 'USER_STATUS_NOT_APPLICABLE' | 'USER_NOT_ELIGIBLE_TO_APPROVE' | 'USER_NOT_APPROVED' | 'USER_APPROVED', required: The authenticated user's approval status for this request. - `quorumStatus` QuorumStatus, nullable: The approval quorum's structure and progress for this request. `null` when `quorumStatusMode` is omitted or `NONE`. Also `null` on an otherwise successful response when the quorum cannot be reported faithfully — a multi-tier request in a workspace that does not maintain per-tier approval counts — so absence here does not imply the request has no quorum. The object may carry additional backend-defined fields beyond those documented. - `requestStatus` 'PENDING' | 'APPROVED' | 'REJECTED' | 'CANCELLED' | 'TIMED_OUT' | 'FAILED', required: The approval request's overall state. Anything other than `PENDING` means the request is no longer awaiting approvals. - `users` QuorumUser[]: Every user participating in this request's quorum. Returned only for `quorumStatusMode=FULL`; omitted otherwise. - `index` integer, required: Zero-based position of this user within the `users` array. The `members` arrays elsewhere in the document reference users by this index rather than repeating the user ID. - `userId` string, required: The participating user's ID. - `status` 'APPROVED' | 'PENDING', required: Whether an approval requirement has been met. Treat this as authoritative rather than comparing the counts yourself: a group can show `currentApprovalCount` equal to `threshold` and still be `PENDING` when the request additionally requires the workspace owner's approval. - `isMandatoryOwner` boolean: Present and `true` only for the workspace owner, when this request additionally requires the owner's approval. Absent for every other participant. - `quorum` union, required: The approval criteria and how far they have been met. `type` discriminates the two shapes: `SIMPLE` flattens the common single-tier case, `RULESET` is the general multi-tier form. - SimpleQuorum: The flattened shape used when the request has a single sub-request with a single tier, which is the common case. The threshold and approval count sit directly on the quorum object instead of inside `rulesets`. - `type` 'SIMPLE', required: Discriminator identifying the flattened single-tier shape. - `threshold` integer, required: Number of approvals this request requires. - `currentApprovalCount` integer, required: Approvals collected so far toward `threshold`. - `status` 'APPROVED' | 'PENDING', required: Whether an approval requirement has been met. Treat this as authoritative rather than comparing the counts yourself: a group can show `currentApprovalCount` equal to `threshold` and still be `PENDING` when the request additionally requires the workspace owner's approval. - `isMandatoryOwnerApproved` boolean: Present only when this request additionally requires the workspace owner's approval. `false` means the owner has not approved yet, which is why `status` can remain `PENDING` even once `currentApprovalCount` reaches `threshold`. Absent when no owner approval is required. - `members` integer[]: Indexes into the top-level `users` array identifying the users who may approve. Returned only for `quorumStatusMode=FULL`; omitted otherwise. - RulesetQuorum: The general shape, used when the request has more than one sub-request or a sub-request with more than one tier. Each entry in `rulesets` is a sub-request; each of its `groups` is a tier. - `type` 'RULESET', required: Discriminator identifying the multi-tier shape. - `rulesetMatch` 'ALL' | 'ANY', required: Whether every sub-request in `rulesets` must be satisfied (`ALL`) or any single one of them (`ANY`). - `status` 'APPROVED' | 'PENDING', required: Whether an approval requirement has been met. Treat this as authoritative rather than comparing the counts yourself: a group can show `currentApprovalCount` equal to `threshold` and still be `PENDING` when the request additionally requires the workspace owner's approval. - `isMandatoryOwnerApproved` boolean: Present only when this request additionally requires the workspace owner's approval. `false` means the owner has not approved yet. Absent when no owner approval is required. - `rulesets` QuorumRuleset[], required: The sub-requests of the approval criteria, evaluated according to `rulesetMatch`. - `groupMatch` 'ALL' | 'ANY', required: Whether every tier in `groups` must be satisfied (`ALL`) or any single one of them (`ANY`). - `status` 'APPROVED' | 'PENDING', required: Whether an approval requirement has been met. Treat this as authoritative rather than comparing the counts yourself: a group can show `currentApprovalCount` equal to `threshold` and still be `PENDING` when the request additionally requires the workspace owner's approval. - `groups` QuorumGroup[], required: The tiers of this sub-request, evaluated according to `groupMatch`. - … - `next` string: Cursor for the next page of results. Pass it back as the `pageCursor` query param to fetch the next page. Empty or absent when this is the last page. ## Other responses - `default`: Error Response --- [API](https://skmtc.dev/fireblocks/apis/fireblocks-api.md) - [All operations](https://skmtc.dev/fireblocks/apis/fireblocks-api/llms.txt) - [OpenAPI document](https://skmtc.dev/fireblocks/apis/fireblocks-api/revisions/4eba9965659a?raw)