Get the requirements of a counterparty
/api/v2/counterparties/requirementsWhat a counterparty must give so that your team can pay it, as a form. Send {} first. The answer lists the fields of a POST /counterparties body, which of them are required, and the choices between fields. When the user picks a value for a field with refreshOnChange, send the request again with that value at the field's key. A selection that does not apply is ignored. A selection that Talentir does not support, such as a country it does not pay to or a token it no longer pays out, is 400 VALIDATION_FAILED with the path of the selection: send the request again without it. When no such value changed since the last request, the last answer is the full form: create the counterparty with every required field and one option of each choice. The answer already reflects the tax settings of your team. Saves nothing. Needs counterparties:read or counterparties:write.
What your form must support. Each field has a type. Your form needs one input for each type:
type | Input | Value to send at key |
|---|---|---|
text | A text input. | The typed text. |
email | An email input. | The typed email address. |
date | A date picker. | The date as YYYY-MM-DD. |
select | A select with the options. Show the label of each option, and its description as help. | The value of the selected option. |
declaration | No input. It is an option of a choice: its radio button is the input. | true when the user selects its option. Otherwise leave the key out. |
More types can come: show an unknown type as a text input. Each value is a string, except the true of a declaration.
The form also needs:
- Sections. Group the fields by the part of
keybefore the dot:identity,address,paymentMethod, andtaxIdentity.emailhas no section. Keep the order offieldsandoptions. - Choices. Show each item of
choicesas radio buttons, one for each option, at the position of its first field. Show the inputs of the selected option only, and send only its fields. A field with achoiceis part of that choice. - Required marks. Mark each field with
required: true. - Help text. Use
labelas the label,exampleas the placeholder, anddescriptionas the help text. For a tax id, showlocalNameandformatas a hint. - Checks while the user types. Test
pattern,minLength, andmaxLength. Before you testpattern, change a copy of the value asnormalizesays. Send the value as the user typed it. - A new request. When the user changes a field with
refreshOnChange: true, send this request again with all selections. Then show the form of the new answer, and keep the values of the fields that are still in it.
Build the counterparty form shows each step with an example.
Warning: The rules can change without a new API version. Ask again for each new counterparty, and do not keep a copy.
application/json- body
The values of the fields that an earlier answer marked refreshOnChange, at the same paths as in the body of POST /counterparties. Send {} first. A selection that does not apply is ignored, for example taxClassification for a company outside the US, or vatExempt in a country without VAT. Do not send it in the create body: POST /counterparties refuses it.
identity?|Leave it out until the user chose a type.
address?|Leave it out until the user chose a country.
paymentMethod?|Leave it out until the user chose a payment method.
taxIdentity?|Leave it out until the user chose a tax classification or a VAT status.
CounterpartyRequirements
application/json- response
object*"counterparty_requirements"Type of the object. Always counterparty_requirements.
"counterparty_requirements"fields*array<>Every field the counterparty can give for your team, also the ones in the request, in the order a form shows them. The fields of one choice come one after the other. A field that is not required and in no choice is optional.
choices*array<>The either-or rules, in the order of their first field. A counterparty can be paid, so its missing is empty, when it gives every required field and the fields of one option of each choice. Two choices never share a key.
curl -X POST 'https://www.talentir.com/api/v2/counterparties/requirements' \ -H 'Content-Type: application/json' \ -d '{}'{ "object": "counterparty_requirements", "fields": [ { "key": "address.line1", "label": "string", "type": "text", "required": true, "choice": "vat_status", "localName": "string", "format": "string", "description": "string", "pattern": "string", "normalize": "uppercase", "minLength": 0, "maxLength": 0, "example": "string", "options": [ { "value": "us_ach", "label": "US ACH", "description": "string" } ], "refreshOnChange": true } ], "choices": [ { "id": "vat_status", "label": "Tax identification", "options": [ { "label": "Place of birth", "keys": [ "taxIdentity.birthPlaceCity", "taxIdentity.birthPlaceCountry" ] } ] } ]}Create a counterparty POST
`taxIdentity` is checked against the tax rules 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. Build the form from [`POST /counterparties/requirements`](https://www.talentir.com/docs/v2/reference/counterparties/counterparties.requirements): it gives every field of this body, with the currencies and assets of the payment method, and which fields make the counterparty payable.
Get a counterparty GET
`{id}` is the counterparty id or your `customId`. Needs `counterparties:read`.