Manage counterparties

Create and screen counterparties before using them as payment destinations in Roots.

See API versions and Beta status before using this workflow in production.

Before you begin

Store the Roots person ID that owns the counterparty relationship.
Collect the counterparty's identity and external-account details.
Confirm that the counterparty type and payment rail are enabled for your company.

Create a counterparty

Create a counterparty with POST /frontoffice/counterparties. A counterparty is an external individual or business and its payment destination.

Field	Type	Required	Constraints
`person_id`	string	Yes	ID of the Roots person that owns the relationship.
`relationship_to_person`	string	Yes	`CUSTOMER` or `SELF`.
`counterparty_information`	object	Yes	Identifies a `Business` or `Individual`.
`external_account_information`	object	Yes	Defines a `BankAccount` or `Wallet` and at least one supported rail.
`external_id`	string	No	Your stable reference for the counterparty.
`description`	string	No	Description of the relationship.

{
  "person_id": "person_business_123",
  "external_id": "supplier_northstar_001",
  "relationship_to_person": "CUSTOMER",
  "description": "Primary operating supplier",
  "counterparty_information": {
    "counterparty_type": "Business",
    "business_name": "Northstar Supplies Ltd"
  },
  "external_account_information": {
    "external_account_type": "BankAccount",
    "supported_rails": ["FEDWIRE"],
    "account_title": "Northstar Supplies Ltd",
    "account_number": "123456789",
    "routing_number": "021000021",
    "institution_name": "Example Bank"
  }
}

A counterparty response includes its Roots ID and screening status.

{
  "id": "counterparty_123",
  "person_id": "person_business_123",
  "external_id": "supplier_northstar_001",
  "status": "Pending",
  "name": "Northstar Supplies Ltd",
  "created_at": "2026-08-03T10:15:00Z"
}

Wait for an active counterparty

Treat Pending and Blocked counterparties as non-payable. Only use a counterparty after Roots reports that it is active for the intended payment activity.

Roots screens counterparties at creation, when relevant details change, and at transaction time. Build your integration to retrieve the latest counterparty state before creating a payment.

Update counterparty details

The API reference includes PATCH /frontoffice/counterparties/{counterparty_id}. Changes to identity or external-account details can require a new screening outcome. Retrieve the latest counterparty status after an update before using it again.

Next steps

Manage accounts to prepare the payment source.
Create payments once the counterparty is eligible.
Respond to RFIs and understand holds when Roots requests additional information.