---
updatedAt: 2026-09-30T17:50:34.235Z
---

Fetch the complete documentation index at: https://docs.avvio.xyz/llms.txt. Use this file to discover all available pages before exploring further. Append .md to any documentation page URL to get its markdown version.

# List approvals

`GET https://api.avvio.xyz/business/api/v1/payments/organizations/{orgId}/payouts/approvals`

Payouts and batch runs waiting on your approvers.

When your organization requires M-of-N approval on API payouts, a
`POST /payouts` or a batch `confirm` above the threshold answers **202**
with an approval id instead of a payout. This is that queue.

An approval is a resource of its own, **not a payout status**: the
payout does not exist until the approval executes, and then it begins
at `pending` like any other. An `executed` approval carries the
`payoutId` it became; so does the `payout_approval.executed` event.

**Approving and rejecting are human actions**, done in the dashboard by
an `owner` or `admin` on their own passkey:
`POST .../payouts/approvals/{approvalId}/approve` and
`POST .../payouts/approvals/{approvalId}/reject`. An API key is refused
on both, whatever role its member holds. The initiator cannot approve
their own request, a second vote from the same signer changes nothing,
one rejection is terminal, and a pending request expires after 24 hours.

There is no cursor: `data` holds at most `limit` approvals, newest
first, and older ones are not reachable from this list. Filter by
`status` to see the ones that matter.

## Parameters

- `orgId` (path, required) — The opaque organization id issued to you, normally CUID-shaped (for example `cmsx…`). It is not an `org_`-prefixed alias. Pass it unchanged in every organization-scoped path.
- `status` (query) — One approval status. Unknown values are a 400.
- `limit` (query) — From 1 to 100. Defaults to 50. Outside the range is a `400`, not clamped.

## Example

```bash
curl -s "$AVVIO_BASE_URL/payments/organizations/$AVVIO_ORG_ID/payouts/approvals?status=pending" \
  -H "x-api-key: $AVVIO_API_KEY"
```

## Responses

- `200` — Approvals, newest first.
- `400` — `VALIDATION_ERROR`: `status` is not an approval status, or `limit` is out of range.
- `401` — The key was refused. Nothing ran. - `UNAUTHORIZED`: missing, invalid or revoked, or a key on a route that does not accept one. - `KEY_EXPIRED`: the key passed the expiry it was issued with. Issue a new one; an expired key cannot be rotated. - `KEY_IP_NOT_ALLOWED`: the key is pinned to source addresses and this request came from another.
- `403` — A valid key that may not make this call. Nothing ran. - `FORBIDDEN`: the key belongs to a different organization. - `ACCOUNT_BLOCKED`: API access for your organization is suspended, and every key is refused until we lift it. Contact support.
- `429` — Too many requests. The default ceiling is **100 requests per minute per API credential** on a 60-second window. High-volume payout and reconciliation routes declare a 600/minute override, and batch submission a 30/minute ceiling. A separate 2,000/minute per-source-IP abuse ceiling always applies. Obey `Retry-After`; it is in seconds and is authoritative. A 429 means the request was refused before the handler ran. Retry reads normally; retry an idempotent mutation with its same `Idempotency-Key`.

Machine contract: [partner-payouts.openapi.yaml](/partner-payouts.openapi.yaml), operation `listPayoutApprovals`.