Manage counterparties

Create and screen counterparties before using them as destinations for Roots withdrawal transfers.

See API availability before you use counterparty operations in production.

Before you begin

Obtain a bearer access token.
Generate an Idempotency-Key for counterparty creation.
Collect the counterparty name, type, supported rail, and required bank details.

Create a counterparty

Create a counterparty with POST /api/v1/client/counterparties.

Field	Type	Required	Values
`person_id`	string	Yes	Roots person that owns the counterparty relationship.
`counterparty_type`	string	Yes	`BUSINESS` or `INDIVIDUAL`.
`name`	string	Yes	Counterparty name.
`rail`	string	Yes	`ACH`, `FEDWIRE`, or `SWIFT`.
`bank_details`	object	Yes	Bank-account details required for the selected rail.

{
  "person_id": "person_123",
  "counterparty_type": "BUSINESS",
  "name": "Northstar Supplies Ltd",
  "rail": "FEDWIRE",
  "bank_details": {
    "account_number": "12345678",
    "routing_number": "021000021"
  }
}

A counterparty response includes screening information and a masked representation of bank account identifiers.

{
  "id": "cpty_123",
  "person_id": "person_123",
  "counterparty_type": "BUSINESS",
  "name": "Northstar Supplies Ltd",
  "external_account_type": "BANK_ACCOUNT",
  "rail": "FEDWIRE",
  "bank_details": {
    "account_number": "****5678",
    "routing_number": "021000021"
  },
  "status": "active",
  "screening_outcome": "cleared",
  "created_at": "2026-08-10T12:00:00Z"
}

Roots accepts full bank details on creation but does not return them in later reads. Store source bank details only in your approved secure system.

Check screening before a transfer

Retrieve the counterparty with GET /api/v1/client/counterparties/{counterparty_id} before creating a withdrawal transfer. Require a current status and screening outcome that permit the intended activity.

The public schema does not enumerate counterparty status or screening-outcome values. Treat an unknown, pending, blocked, or otherwise non-cleared outcome as non-payable until Roots confirms the permitted action.

List counterparties

Use GET /api/v1/client/counterparties with person_id_filter, status_filter, page, and page_size to retrieve counterparty records.

⚠️
The schema permits creation of SWIFT counterparties, but transfer creation currently supports only ACH and FEDWIRE. Do not create a transfer to a SWIFT counterparty until Roots publishes support for that rail.

Next steps

Read Manage accounts to verify the source account balance.
Read Create transfers to create an ACH or Fedwire withdrawal.
Read Security and data handling for bank-detail handling.