All documentation
Documentation
Approval authority is separate from payout submission. Grant approvals:read to read the queue and approvals:write to decide requests. Existing keys do not gain these permissions automatically; payouts:write alone is insufficient. Write does not imply read.
Read requests
| Method and path | Result |
|---|---|
GET /sdk/v1/payout-approvals |
Paginated queue/history |
GET /sdk/v1/payout-approvals/:id |
One agency-owned approval |
GET /sdk/v1/payout-approvals/pending-count |
{ success: true, count } |
GET /sdk/v1/payout-approvals/selection-preview |
{ success: true, selection } for a filtered pending selection |
All require approvals:read. List parameters include page, pageSize (maximum 100), status (comma-separated), excludeStatuses, ids (approval UUIDs), search, sourceType, fromDate, toDate, campaignId, submittedBy=me, sortBy, and sortOrder. me refers to the SDK application that submitted the request. Statuses are PENDING, APPROVING, APPROVED, REJECTED, and CANCELLED.
Decide one request
| Method and path | Body |
|---|---|
POST /sdk/v1/payout-approvals/:id/approve |
{} |
POST /sdk/v1/payout-approvals/:id/reject |
{ "rejectionNote": "Please correct the amount" } |
POST /sdk/v1/payout-approvals/:id/cancel |
{} |
All require approvals:write. IDs are approval UUIDs. Decisions atomically claim a pending request; an already decided request returns 409. Cross-agency IDs return 404. Cancellation is limited to the application that originally submitted the request. Use rejection when the integration is deciding someone else's pending request.
Bulk decisions
POST /sdk/v1/payout-approvals/bulk-approve, /bulk-reject, and /bulk-cancel accept:
{ "approvalIds": ["00000000-0000-4000-8000-000000000001"] }
Bulk rejection also accepts rejectionNote. Inspect each row of the result: a successful HTTP response can contain individual failures. Bulk cancellation preserves the original-submitter restriction.
For bulk approval, use a stable x-idempotency-key when retrying. To approve a filtered selection, first call selection-preview, then send the returned IDs with selectionFingerprint and selectionFilters; stale selections are rejected by the existing approval workflow. Read the queue after any uncertain outcome before submitting a fresh decision.
