Idempotency

POST /payout is an upsert keyed on customId. There is no separate idempotency-key header.

How it works

Give every payout a stable customId from your own system (an order ID, a campaign line, an invoice number):

• If no payout with that customId exists for your team, one is created.
• If one exists, the request updates it instead of creating a duplicate.

The response tells you which happened:

{
  "id": "0e4ba886-0bfe-4b6a-ae2e-d6d9d135dd1e",
  "customId": "campaign-42",
  "status": "created",
  "action": "updated"
}

So a timeout-and-retry loop is safe: send the same request again and you get the same payout back with action: "updated".

Locking a payout down

If the payout must not change after creation — for example when the request data comes from a signed source — create it with payoutType: "manual-immutable". Source-of-truth fields then cannot be updated afterwards; an attempt returns HTTP 409.

Look up by your own ID

GET /payout/{id} accepts either the Talentir id (UUID) or your customId — pass id_type=custom_id as a query parameter. See the generated Payouts reference for details.

What is not idempotent

Session minting (POST /session/*) returns a fresh URL each call; that is by design (URLs are stateless and disposable). Webhook subscription creation is not keyed — check GET /webhook before subscribing if you might retry.