Documentation / SDK v1

Payout approvals

Read pending approval requests and approve, reject, or cancel them.

payout approvals · json
{ "approvalIds": ["00000000-0000-4000-8000-000000000001"] }
All 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.

Describe your program.

Grade turns it into a program it can track and pay.