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.

Recipient invoices

By default Talentir issues a self-billing invoice in the recipient's name for every payout and returns it as recipientInvoice. With the invoice_upload feature enabled for your organization, recipients can upload their own invoice while claiming instead. Talentir reads the document and checks it against the payout: the amount and currency, the party it is addressed to, the issuer, and the VAT treatment. Self-billing stays available. recipientInvoiceSource on the payout tells you which document you got.

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.

Delete a payout

A payout can be deleted as long as no recipient has requested it, i.e. while its status is created, approved or expired. Deleting emits a webhook event with status deleted.

curl -X DELETE "$BASE_URL/payout/{id}" \
  -H "Authorization: Bearer $TALENTIR_API_KEY"

Add ?id_type=custom_id to delete by your own customId. A requested or completed payout cannot be deleted; the request fails with HTTP 409. Deleting an already deleted payout succeeds and returns it unchanged.

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