Create a payout

POST /payout creates (or updates) a payout for a recipient. The recipient does not need a Talentir account yet — they claim the payout later through a hosted session.

Identify the recipient

Pick a verificationMethod that matches what you know about the recipient:

The recipient proves control of that identity during the claim flow — for social handles by connecting the account, for email by signing in with a one-time code.

Request

curl -X POST "$BASE_URL/payout" \
  -H "Authorization: Bearer $TALENTIR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Payment for YouTube channel campaign",
    "creatorHandle": "@mrbeast",
    "verificationMethod": "youtube-channel",
    "payoutAmount": "100.00",
    "currency": "EUR",
    "customId": "campaign-42"
  }'

Useful optional fields:

• customId — your identifier. Sending the same customId again updates the existing payout instead of creating a duplicate; the response's action field says created or updated. See Idempotency.
• payoutType — manual (default) or manual-immutable (source-of-truth fields cannot be updated after creation).
• availableOn — a UTC calendar date (YYYY-MM-DD) from which the payout can be claimed. Omit for immediately claimable.
• tags — free-form strings for categorizing payouts; filterable in GET /payouts.
• notifications — allowed (default) or not-allowed if you run your own notification system.
• preApproved — create the payout already approved. Requires the payouts:approve scope; see Approve and execute payouts.

Currencies: USD, EUR, CHF, GBP. Amounts are decimal strings, minimum 0.1.

For every parameter and the full response schema, see the generated Payouts reference pages.

Balance enforcement

For teams with balance enforcement enabled (the default), pre-approved payouts are rejected with HTTP 422 and error code INSUFFICIENT_BALANCE when the total of all open (approved but not yet paid out) payouts would exceed the team wallet balance. The error data contains walletBalance, totalOpenAmount, and currency.

Sandbox test scenarios

In the sandbox, every payout method has a passing and a failing scenario. Success is the default: any regular recipient details settle the payout instantly and synchronously, including the webhook events a real payout would emit. To exercise the failure path, have the recipient claim with these magic values:

A triggered failure behaves like a real provider rejection: the transfer is dispatched, then declined, and the payout never reaches completed (no completed webhook fires; the payout stays requested while the failure is handled).