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