List approvals

Payouts and batch runs waiting on your approvers.

GET

GET/payments/organizations/{orgId}/payouts/approvals

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

const res = await fetch(`${process.env.AVVIO_BASE_URL}/payments/organizations/${process.env.AVVIO_ORG_ID}/payouts/approvals?status=pending`, {
  headers: {
    'x-api-key': process.env.AVVIO_API_KEY,
  },
});
console.log(res.status, await res.json());

import os
import requests

res = requests.get(
    f"{os.environ['AVVIO_BASE_URL']}/payments/organizations/{os.environ['AVVIO_ORG_ID']}/payouts/approvals",
    headers={
        "x-api-key": os.environ["AVVIO_API_KEY"],
    },
    params={
        "status": "pending"
    },
)
print(res.status_code, res.json())

200OK

{
  "data": [
    {
      "id": "cmf3k2xf90008q8b7q4r6s8tu",
      "kind": "payout",
      "status": "pending",
      "requiredApprovals": 2,
      "approvals": 1,
      "amount": "12000.00",
      "currency": "USD",
      "destinationAccountId": "sbx_acct_MXN_4471_ae66cbc5",
      "createdAt": "2026-09-03T10:00:00.000Z",
      "expiresAt": "2026-09-04T10:00:00.000Z",
      "updatedAt": "2026-09-03T10:12:41.000Z"
    }
  ]
}

{
  "type": "VALIDATION_ERROR",
  "status": 400,
  "detail": "status must be one of: pending, approved, rejected, expired, executing, executed, execution_failed, execution_unknown.",
  "resolution": "Correct the fields listed in `errors` and retry.",
  "errors": [
    "status: \"waiting\" is not an approval status"
  ],
  "requestId": "req-a6t",
  "message": "status must be one of: pending, approved, rejected, expired, executing, executed, execution_failed, execution_unknown.",
  "statusCode": 400
}

{
  "type": "UNAUTHORIZED",
  "status": 401,
  "detail": "Invalid API key",
  "resolution": "Check the API key was copied whole and has not been revoked.",
  "requestId": "req-9bz",
  "message": "Invalid API key",
  "statusCode": 401
}

{
  "type": "FORBIDDEN",
  "status": 403,
  "detail": "This API key cannot access that organization",
  "resolution": "This key is scoped to a different organization.",
  "requestId": "req-9d0",
  "message": "This API key cannot access that organization",
  "statusCode": 403
}

{
  "type": "RATE_LIMITED",
  "status": 429,
  "detail": "ThrottlerException: Too Many Requests",
  "resolution": "Back off and retry after the Retry-After interval.",
  "requestId": "req-9e1",
  "message": "ThrottlerException: Too Many Requests",
  "statusCode": 429
}

Path parameters

orgIdstringRequired
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.

Query parameters

statusstringOptional
One approval status. Unknown values are a 400.
Allowed values:pendingapprovedrejectedexpired
Show 4 more values
executingexecutedexecution_failedexecution_unknown
limitintegerOptionalDefaults to 50
From 1 to 100. Defaults to 50. Outside the range is a 400, not clamped.

Behavior

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.

Responses

200Approvals, newest first.

Body

dataarray of objectRequired
Show 14 properties
- idstringRequired
- kindstringRequired
  Allowed values:payoutpayout_batch
- statusstringRequired
  The lifecycle of an approval, a pre-payout resource. executing and execution_unknown are visible on the resource but emit no event.
  Allowed values:pendingapprovedrejectedexpired
  Show 4 more values
  executingexecutedexecution_failedexecution_unknown
- requiredApprovalsintegerRequired
  M, snapshotted when the request was created.
- approvalsintegerRequired
  Approve votes so far.
- payoutIdstringOptional
  Present once a payout approval is executed, naming the payout it became.
- batchIdstringOptional
  Present on payout_batch approvals.
- amountstring | nullRequired
  Source-currency amount; for a batch, the run's estimated total.
- currencystring | nullRequired
- destinationAccountIdstringOptional
- errorobject | nullOptional
  Present on execution_failed and execution_unknown: why the approved payout could not be sent, or why its outcome is unknown.
  Show 2 properties
  - codestringOptional
    The error type the send answered with, when there was one (PAYOUT_OUTCOME_UNKNOWN on execution_unknown).
  - messagestringRequired
- createdAtstring<date-time>Required
- expiresAtstring<date-time> | nullRequired
  A pending request expires 24 hours after creation.
- updatedAtstring<date-time>Required

Errors

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.

Error body · Error

typestringRequired
Stable machine-readable code.
detailstringRequired
What went wrong, in a sentence. Always a string, so detail.toLowerCase() is safe.
More
This is the field to read on BAD_REQUEST and PROVIDER_REJECTED, where the type alone does not name the condition.
messagestringRequired
The same text as detail, kept for integrations written before detail existed. Read detail.
resolutionstringOptional
What to do about it, when there is a specific answer. It is not on every error (it is absent on BAD_REQUEST, NOT_FOUND, PAYOUT_NOT_CANCELABLE and DESTINATION_ACCOUNT_NOT_FOUND), so treat it as optional and fall back to detail.
statusintegerRequired
HTTP status, repeated in the body.
statusCodeintegerRequired
The same value as status, kept for integrations written before status existed. Read status.
requestIdstringRequired
Quote this to support and we can find the exact request. Also sent as the x-request-id response header, which is the only place it appears on a successful response. Success bodies do not carry it. Send your own x-request-id on the request and we use it, so your trace and ours share one identifier; otherwise we mint one.
errorsarray of stringOptional
Present on VALIDATION_ERROR; names each field that failed.
originalIdempotencyKeystringOptional
On DUPLICATE_REQUEST_DETECTED only. Send the request again with this to receive the original payout instead of making a second one. Without it there is no way to recover except by risking a double payment.
originalPayoutIdstringOptional
On DUPLICATE_REQUEST_DETECTED only. The payout the first request created.
originalBatchIdstringOptional
On a batch DUPLICATE_REQUEST_DETECTED. The run the first request created.
originalRequestIdstringOptional
On a 409 PAYOUT_OUTCOME_UNKNOWN replay. The requestId of the call whose outcome is unknown; quote it to support.
existingRecipientIdstringOptional
On BANK_ACCOUNT_ALREADY_LINKED. The recipient in your organization that already holds this account.
existingMethodIdstringOptional
On BANK_ACCOUNT_ALREADY_LINKED. The payment method on that recipient.

Branch on type, never on the status or the message. Every error type is listed with what to do about it.

Avvio Partner Payouts · Approvals · operation listPayoutApprovals

Try it: List approvals

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

API key Required

Test keys only. Sent as x-api-key through this site's proxy to the Avvio API, never saved, and cleared when you close this dialog.

orgId pathRequired

status queryOptional

limit queryOptional

Was this page helpful?