Create a counterparty

POST/api/v2/counterparties

taxIdentity is checked against the rules of GET /countries for the address country and the identity type. Without paymentMethod and taxIdentity the counterparty exists, and missing names what a direct payment still needs. Needs counterparties:write.

Warning: Talentir can change the tax rules, the settlement currencies, and the payout assets at any time, without prior notice. Do not hardcode them. Read the tax fields from GET /countries and the currencies and assets from GET /payment-method-types when you build the form.

Header Parameters

idempotency-key?maxLength(255)

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

TypeScript Definitions

Use the request body type in TypeScript.

identity*|

Who the counterparty is. The type cannot change after create.

customId?|

Your own key for the counterparty. Use it in place of the id wherever a counterparty is referenced.

email?|

Where the claim link goes when a payout to this counterparty is not paid directly.

address*

Where the counterparty lives or is registered.

paymentMethod?||||||||

Where a direct payment goes. Without it, missing names payment_method.

taxIdentity?|

Tax data of the counterparty. Which fields apply, and which are required, comes from GET /countries for the address country and the identity type.

Response Body

`application/json`

curl -X POST "https://example.com/api/v2/counterparties" \  -H "Content-Type: application/json" \  -d '{    "identity": {      "type": "individual",      "firstName": "string",      "lastName": "string"    },    "address": {      "line1": "string",      "city": "string",      "postalCode": "string",      "country": "DE"    }  }'

{  "object": "counterparty",  "id": "counterparty_0e4ba886-0bfe-4b6a-ae2e-d6d9d135dd1e",  "customId": "campaign-42",  "identity": {    "type": "individual",    "firstName": "string",    "lastName": "string"  },  "email": "jane@example.com",  "address": {    "line1": "string",    "line2": "string",    "city": "string",    "state": "string",    "postalCode": "string",    "country": "DE"  },  "paymentMethod": {    "type": "bank_iban",    "iban": "string",    "currency": "string"  },  "taxIdentity": {    "taxId": "string",    "vatNumber": "string",    "dateOfBirth": "2026-10-01",    "birthPlaceCity": "string",    "birthPlaceCountry": "DE",    "registrationNumber": "string"  },  "recipientManaged": true,  "missing": [    "address"  ],  "createdAt": "2026-09-24T10:00:00.000Z",  "updatedAt": "2026-09-24T10:00:00.000Z"}

Header Parameters

Request Body

Response Body

201application/json

400application/json

401application/json

403application/json

404application/json

409application/json

500application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`