Create a Counterparty
This guide will walk you through how to create a counterparty via API. You can also create counterparties manually in our dashboard here.
Pre-Requisites
Organization ID: and API Key: Found in your developer settings.
1. Collect Counterparty details
You may already have the Counterparty details, having collected them perhaps in your own UI or other means. Once these details are collected, you will create a Counterparty using the API.
2. Create Counterparty
Creating a Counterparty without an account
If you do not know your Counterparty's account information, you can still create a Counterparty record and add an account later.
{
"name": "Kenner, Bach & Ledeen",
"email": "[email protected]"
}{
"id": "74a11899-d0fc-42d2-8a53-0c382d1ec74b",
"object": "counterparty",
"live_mode": false,
"name": "Kenner, Bach & Ledeen",
"email": "[email protected]",
"send_remittance_advice": false,
"verification_status": "unverified",
"legal_entity_id": null,
"metadata": {},
"accounts": [],
"discarded_at": null,
"created_at": "2024-04-25T23:59:44Z",
"updated_at": "2024-04-25T23:59:44Z"
}Creating a Counterparty with an account
The following request will create a Counterparty with just a name and a single account.
{
"name": "Kenner, Bach & Ledeen",
"accounts": [
{
"account_details": [
{
"account_number": "123456789"
}
],
"routing_details": [
{
"routing_number": "026009593",
"routing_number_type": "aba"
}
]
}
]
}{
"id": "37ab9632-642b-40cc-8771-80b38b8ede83",
"object": "counterparty",
"live_mode": false,
"name": "Kenner, Bach & Ledeen",
"email": null,
"send_remittance_advice": false,
"verification_status": "unverified",
"legal_entity_id": null,
"metadata": {},
"accounts": [
{
"id": "b99b3d43-a431-4f2f-838f-92d6b289fdfa",
"object": "external_account",
"live_mode": false,
"account_type": "other",
"party_name": "Kenner, Bach & Ledeen",
"party_type": null,
"party_address": null,
"account_details": [
{
"id": "3ca53c69-e06d-4a6a-818a-0c680744dd3f",
"object": "account_detail",
"live_mode": false,
"account_number": "123456789",
"account_number_safe": "6789",
"account_number_type": "other",
"discarded_at": null,
"created_at": "2024-04-26T00:11:02Z",
"updated_at": "2024-04-26T00:11:02Z"
}
],
"routing_details": [
{
"id": "32e17572-cb4a-49d0-8631-c6542fcc203a",
"object": "routing_detail",
"live_mode": false,
"payment_type": null,
"routing_number": "026009593",
"routing_number_type": "aba",
"bank_name": "Bank of America National Association",
"bank_address": {
"id": "882bb03d-dd51-4a97-92cc-032d7326e3f8",
"object": "address",
"live_mode": false,
"line1": "115 W 42nd St",
"line2": "One Bryant Park",
"locality": "New York",
"region": "NY",
"postal_code": "10036",
"country": "US",
"created_at": "2024-04-26T00:11:02Z",
"updated_at": "2024-04-26T00:11:02Z"
},
"discarded_at": null,
"created_at": "2024-04-26T00:11:02Z",
"updated_at": "2024-04-26T00:11:02Z"
}
],
"name": null,
"metadata": {},
"verification_status": "unverified",
"contact_details": [],
"ledger_account_id": null,
"discarded_at": null,
"created_at": "2024-04-26T00:11:02Z",
"updated_at": "2024-04-26T00:11:02Z"
}
],
"discarded_at": null,
"created_at": "2024-04-26T00:11:02Z",
"updated_at": "2024-04-26T00:11:02Z"
}{
"name": "Acme Fireblocks Wallet",
"accounts": [
{
"account_details": [
{
"account_number": "0x9bE868839163E128971Bb6AE045e172Fa806E805",
"account_number_type": "ethereum_address"
}
]
}
]
}{
"id": "fb9d6c24-da0b-4b43-81ef-e84440d928c0",
"object": "counterparty",
"live_mode": true,
"name": "Acme Fireblocks Wallet",
"email": null,
"send_remittance_advice": false,
"verification_status": "verified",
"external_id": null,
"legal_entity_id": null,
"metadata": {},
"accounts": [
{
"id": "dca61c52-f215-4449-bba8-b7b1efc3c5a4",
"object": "external_account",
"live_mode": true,
"account_type": "other",
"party_name": "Acme Fireblocks Wallet",
"party_type": null,
"party_address": null,
"account_details": [
{
"id": "ba9eb4d1-2423-4c05-a65b-e69ad78fe489",
"object": "account_detail",
"live_mode": true,
"account_number": "0x9bE868839163E128971Bb6AE045e172Fa806E805",
"account_number_safe": "E805",
"account_number_type": "ethereum_address",
"discarded_at": null,
"created_at": "2026-01-22T00:30:18Z",
"updated_at": "2026-01-22T00:30:18Z"
}
],
"routing_details": [],
"name": null,
"metadata": {},
"verification_status": "unverified",
"verification_source": null,
"external_id": null,
"contact_details": [],
"ledger_account_id": null,
"discarded_at": null,
"created_at": "2026-01-22T00:30:18Z",
"updated_at": "2026-01-22T00:30:18Z"
}
],
"discarded_at": null,
"created_at": "2026-01-22T00:30:18Z",
"updated_at": "2026-01-22T00:30:18Z"
}Creating a Counterparty with a Legal Entity
When a Counterparty is linked to a Legal Entity:
- Outgoing payment orders automatically populate receiving-party fields (email, phone, date of birth, tax ID) from the Legal Entity.
- The Counterparty's
nameandemaildefault from the Legal Entity if not provided explicitly. - The dashboard shows bidirectional navigation between the Counterparty and Legal Entity.
- You can filter counterparties by Legal Entity using
GET /counterparties?legal_entity_id=<id>.
Inline creation
You can create both in a single API call by passing a legal_entity object in the request body. The name field is optional when a legal_entity is provided — it defaults from the Legal Entity's name.
{
"name": "Harry Potter",
"legal_entity": {
"legal_entity_type": "individual",
"first_name": "Harry",
"last_name": "Potter",
"date_of_birth": "1990-02-06",
"email": "[email protected]",
"phone_numbers": [
{
"phone_number": "+12125551234"
}
],
"addresses": [
{
"line1": "119 5th Ave",
"line2": "Suite 600",
"locality": "New York",
"region": "NY",
"postal_code": "10003",
"country": "US",
"address_types": ["residential"]
}
],
"identifications": [
{
"id_number": "111222333",
"id_type": "us_ssn",
"issuing_country": "US"
}
]
}
}{
"name": "Hogwarts Inc.",
"legal_entity": {
"legal_entity_type": "business",
"business_name": "Hogwarts Inc.",
"legal_structure": "corporation",
"date_formed": "1800-01-01",
"email": "[email protected]",
"phone_numbers": [
{
"phone_number": "+12125551234"
}
],
"addresses": [
{
"primary": true,
"line1": "119 5th Ave",
"line2": "Suite 600",
"locality": "New York",
"region": "NY",
"postal_code": "10011",
"country": "US",
"address_types": ["business"]
},
{
"primary": false,
"line1": "200 Park Ave",
"line2": "Suite 100",
"locality": "New York",
"region": "NY",
"postal_code": "10012",
"country": "US",
"address_types": ["business_registered"]
}
],
"identifications": [
{
"id_number": "123456789",
"id_type": "us_ein",
"issuing_country": "US"
}
]
}
}Linking an existing Legal Entity
If you have already created a Legal Entity and want to link it to a new Counterparty, pass the legal_entity_id instead:
{
"name": "Harry Potter",
"legal_entity_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}Linking an existing Counterparty to a new Legal Entity
You can also link in the other direction: pass counterparty_id when creating a Legal Entity via POST /legal_entities to link an existing Counterparty to the new Legal Entity.
{
"legal_entity_type": "individual",
"first_name": "Harry",
"last_name": "Potter",
"counterparty_id": "<counterparty_id>"
}For the full Legal Entity field reference, including beneficial owners and control persons for businesses, see Onboard a Business and Onboard an Individual.
For more examples, see the section on Counterparty Example Requests .