API Docs
API referencePayouts

Approve payouts in one request

POST/api/v2/payouts/approve

Approves up to 100 payouts and reserves their sum against the team balance in one decision. andThen runs send-claim-link or pay for every payout. All or nothing: one failing item fails the request with that item's code and error.index, and nothing is applied. Needs payouts:approve, plus payouts:write with andThen: "pay".

Header Parameters

idempotency-key?string

Client-chosen key, 1 to 255 characters (a UUID is recommended). The same key on the same endpoint within 24 hours replays the stored response with Idempotent-Replayed: true.

Length1 <= length <= 255

Request Body

application/json
  1. body
ids*array<>

Payout ids or your customIds, 1 to 100, each once. The response lists the payouts in this order.

Items1 <= items <= 100
andThen?|

Runs send_claim_link or pay in the same request, all or nothing. pay also needs payouts:write.

Response Body

Success

application/json
  1. response
object*"list"

Type of the object. Always list.

Value in"list"
data*array<>

Every item. This list is never paged.

Example Request
curl -X POST 'https://www.talentir.com/api/v2/payouts/approve' \  -H 'Content-Type: application/json' \  -d '{  "ids": [    "payout_0e4ba886-0bfe-4b6a-ae2e-d6d9d135dd1e"  ]}'
Example Response
{  "object": "list",  "data": [    {      "object": "payout",      "id": "payout_0e4ba886-0bfe-4b6a-ae2e-d6d9d135dd1e",      "customId": "campaign-42",      "description": "string",      "amount": "100.00",      "currency": "USD",      "recipient": {        "type": "email",        "email": "jane@example.com",        "phone": "string"      },      "status": "created",      "locked": true,      "availableOn": "2026-10-01",      "availableInDays": -9007199254740991,      "servicePeriod": {        "start": "2026-10-01",        "end": "2026-10-01"      },      "expiresAt": "2026-09-24T10:00:00.000Z",      "tags": [        "string"      ],      "paymentMethod": {        "type": "crypto",        "asset": "string",        "currency": "EUR"      },      "withInvoice": true,      "senderInvoiceUrl": "string",      "recipientInvoiceUrl": "string",      "recipientInvoiceSource": "self_billing",      "failureCode": "account_closed",      "failureReason": "string",      "approvedAt": "2026-09-24T10:00:00.000Z",      "recipientNotifications": "enabled",      "claimLinkSentAt": "2026-09-24T10:00:00.000Z",      "requestedAt": "2026-09-24T10:00:00.000Z",      "retry": {        "url": "string",        "code": "account_closed",        "reason": "string"      },      "completedAt": "2026-09-24T10:00:00.000Z",      "createdAt": "2026-09-24T10:00:00.000Z",      "updatedAt": "2026-09-24T10:00:00.000Z"    }  ]}

Pay a counterparty directly POST

Sends the money to the counterparty's saved payment method. Settlement is asynchronous; `payout.completed` or `payout.failed` follows. A `failed` payout is paid again with the same call. Needs `payouts:write`, plus `payouts:approve` for a `failed` payout: it goes to the counterparty's current payment method, which the approval did not cover.

Send claim links in one request POST

Emails the claim link for up to 100 payouts. Every payout is checked before the first email goes out. All or nothing: one failing item fails the request with that item's code and `error.index`, and nothing is applied. Needs `payouts:write`.