Create a Counterparty

Create a Counterparty.

Idempotency-Keystring required

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

Request body

customerIdstring required

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

namestring required

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

entityType'individual' | 'business'

emailstring

Contact email address.

phonestring

Phone in E.164 format.

taxIdstring

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

dateOfBirthstring date

Date of birth (YYYY-MM-DD).

nationalitystring

ISO 3166-1 alpha-2.

metadataobject

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

Example request

{
  "customerId": "cst_vfa0nxw6zvyws9g237jrxn4y7k",
  "name": "Alice Smith",
  "entityType": "individual",
  "address": {
    "line1": "500 Market Street",
    "city": "San Francisco",
    "state": "CA",
    "country": "US",
    "zipCode": "94105"
  },
  "email": "alice@example.com",
  "phone": "+14155550100",
  "nationality": "US"
}

Response

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

idstring

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

object'counterparty'

customerIdstring

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

status'active' | 'rejected' | 'deleted'

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.

rejectionReasonstring

Set when status = rejected.

namestring

Full legal name or registered business name.