Migrate from v1 to v2

API v2 lives at /api/v2. It runs next to v1, and a v1 integration keeps working until v1's sunset date. That date is announced at least 90 days ahead.

Payouts, counterparties, and the team are shared. A payout you created through v1 is readable and manageable through v2, and the other way round. The JSON shape differs, and so does some behavior; this guide lists both. Webhooks are not shared: v1 and v2 each see only their own webhooks.

Two v1 rules changed together with v2. A customId is unique per team, not across all teams. And a deleted payout is final: v1 POST /payout with its customId or its id fails instead of bringing the payout back. Its customId stays taken.

Base URL and authentication

Authentication does not change. Send your API key or OAuth access token as Authorization: Bearer <token>. The OpenAPI document is at /api/v2/spec.json.

v2 accepts an OAuth token that is bound to /api/v1. v1 does not accept a token that is bound to /api/v2. While your integration still calls v1, request tokens with resource=<base_url>/api/v1, also when the user authorizes again for the new scopes. Both versions accept these tokens. See OAuth.

Test the migration in the sandbox first. It has its own teams, API keys, and webhooks.

What v2 adds

• Push payouts. Pay a counterparty's saved bank account, PayPal or Venmo account, or crypto wallet directly, without a claim link: POST /payouts/{id}/pay.
• Counterparties as a resource. Create, read, update, delete, and list the people and companies you pay: /counterparties.
• A country reference. GET /countries returns, for every country Talentir pays to, the tax fields a counterparty from that country needs, split into individual and organization, with the combinations your team must collect. New tax rules appear there, not in a new API version.
• A payment method reference. GET /payment-method-types returns every rail a counterparty can save, with the currencies a fiat rail settles in and the tokens crypto pays out. New currencies and assets appear there, not in a new API version.
• An explicit payout cycle. Create, approve, then either send-claim-link or pay. Talentir emails the claim link only after you call send-claim-link.
• Batch endpoints. Create, approve, send claim links for, or pay 1 to 100 payouts in one request.
• Cursor pagination, one error shape, idempotency keys, prefixed ids, typed webhook events. See Conventions in short.

What v2 removes

• Creating payouts to a TikTok, Instagram, or YouTube handle. v2 creates payouts to an email or to a counterparty only. v2 still returns the handle payouts that v1 created. Their recipient cannot change; their other fields can.
• Creating payouts to a wallet address. To pay a wallet, save it as a counterparty's crypto payment method and pay directly. A recipient who claims can still choose crypto.
• Upsert on POST /payout. v2 POST /payouts only creates. Updates are PATCH /payouts/{id}.
• id_type=custom_id. The {id} in a payout or counterparty path accepts either the prefixed id or your customId.
• offset, order_by, and order_direction on GET /payouts. v2 lists page with a cursor and are always newest first.
• Deprecated v1 fields: uuid, url, whitelabel, teamUuid, depositInfo.

v2 ignores a query parameter it does not know. It does not reject it. A loop that pages with offset gets the first page every time, and id_type has no effect.

Ids

Resource ids in v2 carry a prefix that names the resource:

The part after the prefix is the same value v1 returns. To reuse the payout, counterparty, and team ids you stored from v1, add the prefix. The UUID must be lowercase. A v1 webhook id does not work in v2; see Webhooks. The OAuth team_hint takes the UUID without the prefix.

New resources use the prefixes webhook_, delivery_, event_, and session_. A country id is its ISO code (DE). A payment method type id is its rail name (bank_iban). Team members and accounts have no id.

v2 accepts only the prefixed form. Wherever a payout or counterparty is referenced, a value without the prefix is read as a customId. A bare v1 UUID there finds nothing: a path or a request body returns 404, and the recipientCounterpartyId filter returns an empty list. In a webhook path, a bare UUID returns 400 VALIDATION_FAILED. A value with the prefix but no valid UUID after it, for example payout_123, also returns 400 VALIDATION_FAILED.

A customId:

• has 1 to 255 characters when you set or change it: ASCII letters, digits, ., _, :, and -, starting with a letter or a digit. Such a key is safe in a URL path as is. A key saved through v1 that does not follow this rule is returned as it is and works in lookups, with two exceptions: an empty key, and a key that starts with the resource's prefix, such as payout_…. Look these payouts up by their id.
• must not start with the resource's prefix. customId: "payout_…" is rejected with 400 VALIDATION_FAILED.
• is unique within your team and per resource. Payouts and counterparties have separate spaces.
• is refused on create and on PATCH while another payout or counterparty holds it: 409 CUSTOM_ID_TAKEN, and details.id names the holder.
• stays taken after its payout is deleted, so a repeated create can never pay twice. details.id is then null. To redo a deleted payout, use a new customId.
• is free again after its counterparty is deleted.
• works wherever a payout or counterparty is referenced: the {id} in a path, the ids of a batch request, recipient.counterpartyId, the payoutId and payoutIds of a session, and the recipientCounterpartyId filter. Responses always carry the prefixed id.

A deleted payout or counterparty is gone from the API: every endpoint answers 404 PAYOUT_NOT_FOUND or COUNTERPARTY_NOT_FOUND for it, and lists do not include it. v1 GET /payout/{id} still returns a deleted payout with status deleted. Payouts to a deleted counterparty keep its id in recipient.counterpartyId.

In v1, a POST /payout with a known customId updated that payout. v2 never does.

Requests

• A request body with an unknown field fails with 400 VALIDATION_FAILED. Remove every v1-only top-level field before you send a v2 request: payoutAmount, verificationMethod, email, phone, counterpartyId, creatorHandle, handleType, walletAddress, payoutType, notifications, preApproved, id, whitelabel, and, for webhooks, targetUrl and eventType.
• amount is a decimal string with up to two decimals and a minimum of 0.10, for example "100.00".
• description has 1 to 5000 characters. v1 had no maximum.
• tags is an array of at most 20 tags with 1 to 100 characters each, or you do not send it. null is rejected.
• An email has at most 254 characters. recipient.phone is E.164 with no spaces, for example +4915112345678.
• A calendar date such as availableOn is YYYY-MM-DD and must be a real day. 2026-02-30 is rejected with 400 VALIDATION_FAILED.
• A redirectUrl must be https (http only for localhost) and has at most 2048 characters. v1 accepted http.
• Every create returns 201: payouts, payout batches, counterparties, webhooks, and sessions. v1 returned 200.
• Send Idempotency-Key on every POST. See Idempotency.

Endpoint map

Payout field map

Every top-level field is present in every response. A field with no value is null, never omitted. v1 omitted empty fields. The keys inside recipient and paymentMethod depend on their type.

Status values

failed is new. It applies to a payout that you pushed to a counterparty that you manage, after the provider returned the transfer and Talentir processed the return. Until then, the payout reads requested in both versions. v1 shows a failed payout as completed. failureCode and failureReason say why. Fix the counterparty, then call pay again. The payout goes back to requested in v2 and stays completed in v1.

A returned transfer to a recipient who claimed stays completed in both versions. The recipient claims again with new details.

Payment method values

The payout cycle

In v2, each step is a request you make. The v1 API never emailed the recipient either: with notifications: "allowed", a team member sent the claim link from the dashboard. In v2, Talentir emails the claim link when you call send-claim-link, and sends an SMS too when the payout has a phone number. While the payout stays unclaimed, Talentir sends one reminder 7 days after the latest claim-link email. A second send-claim-link resends the email and moves the reminder, if the reminder has not gone out yet.

send-claim-link needs status approved, an availableOn that is today or earlier, and a recipient email. In another status, it fails with 409 PAYOUT_NOT_CLAIMABLE. For a counterparty recipient, the email is the counterparty's email; without one, the call fails with 422 RECIPIENT_EMAIL_MISSING. A handle or wallet payout that v1 created without an email fails the same way; mint a link for it with POST /sessions.

recipientNotifications says whether Talentir may notify the recipient at all. With the default, enabled, a team member can also send the claim link from the dashboard, as in v1. With disabled, Talentir sends the recipient nothing and the dashboard cannot send the claim link: your system shows or sends a link minted with POST /sessions. A send-claim-link call sets it to enabled. Payouts that v1 created keep their v1 notifications setting and read back as the matching value. If a team member approves payouts in the dashboard and you want Talentir to email them, call send-claim-link when your webhook receives payout.approved, or leave it to the team member.

# 1. create
curl -X POST https://www.talentir.com/api/v2/payouts \
  -H "Authorization: Bearer $TOKEN" \
  -H "Idempotency-Key: payout-create:campaign-42:1" \
  -H "Content-Type: application/json" \
  -d '{ "customId": "campaign-42", "description": "September campaign", "amount": "100.00", "currency": "EUR", "recipient": { "type": "email", "email": "jane@example.com" } }'

# 2. approve (needs payouts:approve)
curl -X POST https://www.talentir.com/api/v2/payouts/campaign-42/approve \
  -H "Authorization: Bearer $TOKEN" \
  -H "Idempotency-Key: payout-approve:campaign-42:1"

# 3. let Talentir email the claim link
curl -X POST https://www.talentir.com/api/v2/payouts/campaign-42/send-claim-link \
  -H "Authorization: Bearer $TOKEN" \
  -H "Idempotency-Key: payout-send-claim-link:campaign-42:1"

For a payout to a counterparty, POST /payouts/{id}/pay pushes the money instead of step 3. pay on a payout to an email fails with 422 RECIPIENT_NOT_COUNTERPARTY.

The steps collapse with one field, andThen. On create, "andThen": "approve", "approve_and_send_claim_link", or "approve_and_pay" runs the later steps in the same request. On approve, the body { "andThen": "send_claim_link" } or { "andThen": "pay" } does the same. The request either records every step or none: a counterparty that cannot be paid fails the whole create with 422 COUNTERPARTY_NOT_PAYABLE and leaves no payout behind. The claim-link email goes out after the payout is saved. If the email fails, the payout stays approved and claimLinkSentAt stays null; call send-claim-link again.

• andThen on create needs payouts:approve. approve with andThen: "pay" also needs payouts:write.
• The pay variants need a counterparty recipient. On create, andThen: "approve_and_pay" without one fails with 400 VALIDATION_FAILED. On approve, andThen: "pay" without one fails with 422 RECIPIENT_NOT_COUNTERPARTY.
• Before a future availableOn, pay, send-claim-link, and every andThen that includes one of them fail with 409 PAYOUT_NOT_YET_AVAILABLE. Use andThen: "approve", then call pay or send-claim-link on or after availableOn.

# create, approve, and pay in one request
curl -X POST https://www.talentir.com/api/v2/payouts \
  -H "Authorization: Bearer $TOKEN" \
  -H "Idempotency-Key: payout-create:INV-42:1" \
  -H "Content-Type: application/json" \
  -d '{ "customId": "INV-42", "description": "September campaign", "amount": "100.00", "currency": "EUR", "recipient": { "type": "counterparty", "counterpartyId": "counterparty_7c1d…" }, "andThen": "approve_and_pay" }'

If you send your own emails, skip step 3 and mint a URL with POST /sessions (type: "payout_claim"), as with v1 POST /session/payout.

Counterparties

A counterparty is the person or company you pay. It holds the name, address, payment method, and tax identity. The counterparties you picked with counterpartyId in v1 are the same records in v2. Add the counterparty_ prefix to a stored counterpartyId.

To create one:

1. Read the recipient's country from the country list:

   GET /api/v2/countries

   The identity and address fields of a counterparty are fixed; the tax identity and the payment method are not. Each country has taxRequirements.individual and taxRequirements.organization. Each of these has fields, an ordered list: each field has a key (the taxIdentity field name), a label, help text in localName, format, and description (each or null), a pattern (or null), and an example (or null). It also has anyOf, the accepted combinations: send every field of any one set. An empty anyOf means no tax data is required. The rules already reflect your team's DAC7 setting; you never evaluate DAC7 yourself. See Pay directly for a full example.

2. Create the counterparty:

   curl -X POST https://www.talentir.com/api/v2/counterparties \
     -H "Authorization: Bearer $TOKEN" \
     -H "Idempotency-Key: counterparty-create:creator-1042:1" \
     -H "Content-Type: application/json" \
     -d '{
       "customId": "creator-1042",
       "identity": { "type": "individual", "firstName": "Jane", "lastName": "Doe" },
       "email": "jane@example.com",
       "address": { "line1": "Musterstraße 1", "city": "Berlin", "postalCode": "10115", "country": "DE" },
       "paymentMethod": { "type": "bank_iban", "iban": "DE89370400440532013000", "currency": "EUR" },
       "taxIdentity": { "taxId": "12345678901", "dateOfBirth": "1990-05-04" }
     }'

   identity and address are required. paymentMethod.currency must be one of the currencies that GET /payment-method-types gives for that type. In the response, missing names the gaps a push payment still has (payment_method, tax_identity, address). An empty missing means POST /payouts/{id}/pay can succeed. GET /counterparties?payable=true lists only the counterparties with an empty missing. The list also filters by type, country, paymentMethodType, and email.

3. Create payouts with "recipient": { "type": "counterparty", "counterpartyId": "counterparty_…" } and pay them with POST /payouts/{id}/pay, or send a claim link if the counterparty has an email. pay to a counterparty whose missing is not empty fails with 422 COUNTERPARTY_NOT_PAYABLE, and details.missing lists the gaps.

Read the country when you build the form, not once at install. When a tax rule changes, the country changes and the API version does not.

A recipient who claims a payout keeps their own details. Their counterparty is in the list with recipientManaged: true, and PATCH and DELETE on it fail with 409 COUNTERPARTY_MANAGED_BY_RECIPIENT. To take over, create a counterparty with the same email. The new counterparty hides the recipient-managed one in GET /counterparties. Payouts that you already created keep their counterparty. Use the new id for new payouts.

Sessions

Team

Lists

v1 GET /payouts returned a bare array and paged with offset and limit. v2 lists return an envelope:

{ "object": "list", "data": [ … ], "hasMore": true, "nextCursor": "eyJ…" }

Send the same filters, in the same order, with every cursor. A cursor with other filters fails with 400 VALIDATION_FAILED. limit can change between pages.

/payouts, /counterparties, /webhooks, /webhooks/{id}/deliveries, and /team/members page with a cursor. /countries, /payment-method-types, /team/accounts, and batch responses are never paged. They have no hasMore and no nextCursor.

Errors

Every error has code, message, and status. details is present only for codes that have it. In a batch, an error about one item also has index, the 0-based position of that item. An error about the whole request has no index: INSUFFICIENT_BALANCE, VERIFICATION_REQUIRED, ALLOWANCE_REQUIRED, MISSING_SCOPE, and the idempotency codes. A body that fails the schema has no index either; the position is in details.issues[].path.

{ "error": { "code": "INSUFFICIENT_BALANCE", "message": "…", "status": 422, "details": { "total": "1000.00", "required": "1200.00", "currency": "EUR" } } }

Branch on code, never on message.

New codes in v2:

An invalid VAT number has no code of its own. It is 400 VALIDATION_FAILED with the path ["taxIdentity", "vatNumber"].

Webhooks

v1 and v2 webhooks are separate. v1 webhooks keep receiving v1 bodies, and v2 webhooks receive v2 bodies. GET /api/v2/webhooks does not show v1 webhooks, and a v1 webhook id does not work in v2. Register a v2 webhook, run both while you migrate, then delete the v1 webhook with v1 DELETE /api/v1/webhook/{id}.

While both run, both receive changes made through either version or the dashboard. v1 bodies keep the bare ids. The webhook url must be a public https URL; to test from your machine, use a tunnel. v2 does not follow redirects; v1 followed up to 20. Register the final URL.

A v2 webhook belongs to the API key or OAuth grant that created or last updated it. It receives an event only while that credential can read the resource. If the key is deleted or disabled, loses the read scope, or the grant is revoked, the webhook stops receiving events and stays enabled. v1 webhooks belong to the team. When you rotate an API key, send PATCH /webhooks/{id} with the new key for each webhook, then delete the old key.

curl -X POST https://www.talentir.com/api/v2/webhooks \
  -H "Authorization: Bearer $TOKEN" \
  -H "Idempotency-Key: webhook-create:1" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://example.com/talentir", "events": ["payout.*", "counterparty.*"] }'

The create response has the signing secret as secret. You see it once; it is null everywhere else except the response of rotate-secret. It is a new secret: v2 deliveries do not use your v1 secret. Both start with whsec_, but they are used in different ways. In v1, the full secret is the HMAC key. In v2, the part after whsec_ is a base64 key, as Standard Webhooks defines it.

v2 records events only while you have an enabled v2 webhook. Changes before you register it are not sent.

Event body

A v1 body was the payout itself, in the v1 shape, with a message string. A v2 body is an event envelope:

{
  "object": "event",
  "id": "event_…",
  "type": "payout.completed",
  "teamId": "team_…",
  "timestamp": "2026-09-24T10:00:00.000Z",
  "apiVersion": "v2",
  "data": { "object": "payout", "id": "payout_…", "status": "completed", "…": "…" }
}

data has the v2 payout shape. Map its fields with the field map. timestamp is when Talentir recorded the event, shortly after the change. message is gone.

v1 sent one payout event, and you read status. v2 names the transition in type:

• payout.updated is sent when the description, amount, currency, tags, customId, availableOn, recipient, or locked changes, and when a payout goes back to created. v1 sent nothing for a change that kept the status.
• webhook.ping is sent by POST /webhooks/{id}/test to the webhook, whatever its events, with the webhook as data.
• Deduplicate on the event id, which is also the webhook-id header. A retry sends the same id.
• Events can arrive out of order, and one request can send several events: andThen: "approve_and_pay" sends payout.created and payout.requested. data is the payout when Talentir records the event, so it can already show a later step: here, the payout.created event has status: "requested". For the current state, read GET /payouts/{id}; a deleted payout answers 404.
• pay on a failed payout sends payout.requested, then payout.completed or another payout.failed.

Signature

v2 webhooks follow Standard Webhooks. v1 webhooks keep their scheme unchanged. In both, verify the raw body, not a re-serialized one.

The X-Talentir-* headers are not sent on v2 webhooks. An official Standard Webhooks library verifies a v2 request for you:

import { Webhook } from "standardwebhooks";

const event = new Webhook(secret).verify(rawBody, headers); // throws when the request is not valid

Each retry has a new webhook-timestamp and a new signature, so deduplicate on webhook-id, not on the signature. See Verify signatures for a check without a library and the timestamp age to accept, and Delivery behavior for the retry schedule.

Give the v2 webhook its own URL. If you must use one URL for both versions, a v2 request has the webhook-signature header, and a v1 request has X-Talentir-Signature. Verify each with its own secret.

Failing endpoints

v1 did not retry a 4xx answer other than 429. It deleted a webhook when your endpoint answered 410, or after 25 other 4xx answers with no successful delivery in between. v2 retries every answer that is not 2xx, 4xx included, for about three days. It sets enabled: false instead of deleting: at once on 410, or after 25 events in a row that fail every attempt. Answer 2xx to event types you do not handle, or the webhook is disabled.

Fix the endpoint, then send PATCH /webhooks/{id} with { "enabled": true }. Events that happened while the webhook was disabled are not sent later. Read their current state with GET /payouts.

Scopes

An existing API key has no counterparties:* scope. Add it in the dashboard under API keys, or create a new key. OAuth clients request the new scopes on /authorize, so the user must authorize again; see Base URL and authentication for the resource to request. payouts:approve is not self-service: Talentir enables it for your team. Without it, approve in the dashboard or with a payout_approval session.

Idempotency

v2 accepts Idempotency-Key on every POST. The header is optional, but without it a retry runs the request again. v1 ignores the header, and v2 ignores it on PATCH and DELETE.

• The key has 1 to 255 characters. It is scoped to your team, the method, and the exact path. /payouts/INV-42/approve and /payouts/payout_…/approve are different paths for the key.
• The same key on the same path replays the stored response with Idempotent-Replayed: true for at least 24 hours. The same key with a different body fails with 409 IDEMPOTENCY_KEY_REUSED.
• A second request while the first one still runs fails with 409 IDEMPOTENCY_KEY_IN_PROGRESS. Retry later with the same key.
• The stored response includes errors. A 4xx from the endpoint's own checks is stored and replayed, and so is a 500 INTERNAL_ERROR, because the request can have done part of its work. Not stored: MISSING_SCOPE, UNAUTHORIZED, and a body that is not JSON or does not match the schema.

The key and customId do different jobs. customId says which payout this is, forever. The key says which request attempt this is, for 24 hours. For a create, derive the key from your business key and an attempt number, for example Idempotency-Key: payout-create:INV-42:1. Retry a network failure with the same key. After a stored error, fix the cause, for example add balance after INSUFFICIENT_BALANCE, and send a new key (payout-create:INV-42:2). After a 500, first check the state with GET /payouts/INV-42, then send a new key if the payout is still missing. A retry after 24 hours gets 409 CUSTOM_ID_TAKEN with the payout's id. Both end on the same payout.

If you do not store an attempt number, send a new random key for each attempt, and use customId to find a payout that already exists: CUSTOM_ID_TAKEN gives its id.

Conventions in short

• Collections are plural nouns: /payouts. The team is a singleton: /team. Operations are verb segments: /payouts/{id}/approve.
• Path segments are kebab-case, JSON fields are camelCase, enum values are snake_case, error codes are SCREAMING_SNAKE_CASE. Event types are dotted: payout.completed.
• Money is a decimal string with a currency field next to it.
• Timestamps end in At, except the event timestamp, and are ISO 8601 UTC with milliseconds. Calendar dates are YYYY-MM-DD.
• Most resources have object, id, createdAt, and updatedAt. A session has createdAt only. A team member has no id and only joinedAt. An account has no id and no timestamps. Countries and payment method types have no timestamps. An event has timestamp.
• Top-level fields of a resource are never omitted; they are null. Arrays are never null, except currencies and assets in GET /payment-method-types: currencies is null for crypto, and assets is null for a fiat rail.
• Ignore fields you do not know. Treat every enum that the reference marks as open as open, with a fallback. These include status, failureCode, recipient.type, paymentMethod.type, currency on read, missing, kybStatus, role, depositInstructions[].type, and event type. On write, a payout currency is exactly USD, EUR, CHF, or GBP. A counterparty's paymentMethod.currency is one of the currencies of its type. See Changes without a new version for what can change.

Checklist

1. Switch the base URL to /api/v2. Test in the sandbox first.
2. Add counterparties:* to your API key. OAuth clients authorize again, with resource=<base_url>/api/v1 while they still call v1. Ask Talentir for payouts:approve if you approve through the API.
3. Prefix stored ids: payout_, counterparty_, team_.
4. Rename fields per the field map. Send amount, not payoutAmount. Send locked, not payoutType. Send andThen: "approve", not preApproved.
5. Replace verificationMethod, email, phone, and counterpartyId with the recipient object. Stop creating handle and wallet payouts.
6. Remove every v1-only field from request bodies. v2 rejects unknown fields. Check the new limits in Requests.
7. Replace update-by-POST with PATCH /payouts/{id}. It works only while status is created and changes only the fields you send.
8. Add the step after approval: send-claim-link, pay, or your own link from POST /sessions.
9. Map status, paymentMethod.type, and kybStatus values. Handle the new status failed. Treat open enums as open.
10. Expect 201 on every create, and null instead of omitted fields.
11. Replace offset paging with cursor. v2 ignores offset. Read data from the list envelope.
12. Read error.code from the new error shape. Move validation handling from 422 to 400.
13. Move sessions to POST /sessions with type. Send prefixed payout ids or your customIds.
14. Read balances from GET /team/accounts and members from GET /team/members.
15. Register a v2 webhook with events[]. Store its secret. Verify each request with a Standard Webhooks library. Read type and data from the envelope. Deduplicate on id. Answer 2xx to event types you do not handle. After an API key rotation, PATCH the webhook with the new key.
16. Send Idempotency-Key on every POST. Retry a network failure with the same key. After a 500, check the state before you send a new key.
17. Delete the v1 webhook with v1 DELETE /api/v1/webhook/{id} once the v2 webhook is verified. Use a v1 API key or a token bound to /api/v1.