API Docs
API referenceCounterparties

Get the requirements of a counterparty

POST/api/v2/counterparties/requirements

What 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:

typeInputValue to send at key
textA text input.The typed text.
emailAn email input.The typed email address.
dateA date picker.The date as YYYY-MM-DD.
selectA select with the options. Show the label of each option, and its description as help.The value of the selected option.
declarationNo 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 key before the dot: identity, address, paymentMethod, and taxIdentity. email has no section. Keep the order of fields and options.
  • Choices. Show each item of choices as 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 a choice is part of that choice.
  • Required marks. Mark each field with required: true.
  • Help text. Use label as the label, example as the placeholder, and description as the help text. For a tax id, show localName and format as a hint.
  • Checks while the user types. Test pattern, minLength, and maxLength. Before you test pattern, change a copy of the value as normalize says. 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.

Request Body

application/json
  1. 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.

Response Body

CounterpartyRequirements

application/json
  1. response
object*"counterparty_requirements"

Type of the object. Always counterparty_requirements.

Value in"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.

Example Request
curl -X POST 'https://www.talentir.com/api/v2/counterparties/requirements' \  -H 'Content-Type: application/json' \  -d '{}'
Example Response
{  "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"          ]        }      ]    }  ]}