Skip to main content
POST
Create a Counterparty

Authorizations

Authorization
string
header
required

Token from POST /auth/token

Headers

Idempotency-Key
string
required

Required on POST and PUT requests. Use a unique value per logical mutation attempt, for example a UUID.

Body

application/json
customerId
string
required

Owning customer (cst_… TypeID or legacy public id).

name
string
required

Full legal name or registered business name. 1..140 chars.

Required string length: 1 - 140
address
object
required

Registered address. Required: must include non-blank line1, city, zipCode and a two-letter ISO country (state required for US).

entityType
enum<string>

individual or business.

Available options:
individual,
business
email
string

Contact email address.

phone
string

Phone in E.164 format.

taxId
string

Tax ID (CPF, CNPJ, SSN, etc.). Required for some external-account types.

dateOfBirth
string<date>

Date of birth (YYYY-MM-DD).

nationality
string

ISO 3166-1 alpha-2.

metadata
object

Free-form key-value pairs stored on the resource and echoed back on reads.

Response

201 - application/json

The request has succeeded and a new resource has been created as a result.

A third party a customer transacts with — an entry in the customer's address book. Counterparties will own External Accounts (registered payment destinations) in a later slice.

address
object
required

Registered address. Required since v0.11 — always present in responses.

id
string

Public TypeID, e.g. txn_01h455vb4pex5vsknk084sn02q; legacy UUID suffixes are accepted until non-v7 rows are retired.

Pattern: ^[a-z]+_([0-9a-hjkmnp-tv-z]{26}|[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})$
object
enum<string>
Available options:
counterparty
customerId
string

Public TypeID, e.g. txn_01h455vb4pex5vsknk084sn02q; legacy UUID suffixes are accepted until non-v7 rows are retired.

Pattern: ^[a-z]+_([0-9a-hjkmnp-tv-z]{26}|[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})$
status
enum<string>

Lifecycle of a counterparty. rejected is reserved for create-time compliance screening (not yet active); deleted marks a soft-deleted record that remains readable by id.

Available options:
active,
rejected,
deleted
rejectionReason
string

Set when status = rejected.

name
string

Full legal name or registered business name.

entityType
enum<string>
Available options:
individual,
business
email
string
phone
string
taxId
string
dateOfBirth
string<date>
nationality
string

ISO 3166-1 alpha-2.

metadata
object
createdAt
string<date-time>
updatedAt
string<date-time>