Create counterparty

Creates a new counterparty (business partner, client, or related entity) with comprehensive profile information and associated bank/crypto accounts.

Endpoint

POST/v2/counterparty

Link

Gateway APIstagep.tst-apidmndelss.com

Request

Headers

Key	Value	Required
Authorization	123	Yes
Content-Type	application/json	Yes
Accept	application/json	Yes

Request Body

Required fields: Required fields — profile

Field	Type	Description	Rules
customerId	string	ID of the customer that will own this counterparty
profile.name	string	Legal entity name	Fewer than 35 characters; no special characters, accents, or leading/trailing spaces.
profile.address.addressLine1	string	Primary address line	Fewer than 35 characters.
profile.address.city	string	City name	Fewer than 21 characters
profile.address.stateIso	string	State code	For US addresses, a two-letter ISO code. Can't be the same value as the country code. For countries without states/provinces, use the region name instead.
profile.address.countryIso	string	Country code (ISO)	two-letter ISO code only
profile.address.postalCode	string	Postal code	For US ZIP codes, either 5 digits, or 5 digits + a hyphen + 4 digits.
profile.additionalInfo.type	string	Entity type: INDIVIDUAL or CORPORATION
profile.additionalInfo.businessLine	string	Industry classification	can't be PLB_OTHER
profile.additionalInfo.relationship	string	Relationship to the customer, e.g. PRC_SUPPLIER, PRC_CUSTOMER, etc.	can't be PRC_NOT_RELATED

json

{
  "customerId": "cust_12345",
  "description": "Primary electronics supplier",
  "profile": {
    "name": "Tech Supplies Corp",
    "email": "[email protected]",
    "phoneNumber": "[phone]",
    "taxNumber": "TAX-US-12345",
    "dateOfBirth": "1985-05-15T00:00:00Z",
    "address": {
      "addressLine1": "123 Main Street",
      "addressLine2": "Suite 500",
      "addressLine3": "Building B",
      "city": "New York",
      "stateIso": "NY",
      "countryIso": "US",
      "postalCode": "10001",
      "unitNumber": "5A"
    },
    "website": "https://techsupplies.com",
    "additionalInfo": {
      "type": "CORPORATION",
      "businessLine": "PLB_HIGH_TECH_SOFTWARE_TELECOMS",
      "relationship": "PRC_SUPPLIER"
    },
    "lastname": "Smith"
  },
  "accounts": [
    {
      "currencyIso": "USD",
      "bank": {
        "name": "Chase Bank",
        "number": "123456789",
        "address": {
          "addressLine1": "456 Bank Street",
          "city": "New York",
          "stateIso": "NY",
          "countryIso": "US",
          "postalCode": "10002"
        },
        "routingNumber": "021000021"
      },
      "fiat": {
        "number": "987654321",
        "routingNumber": "021000021",
        "additionalInformation": {
          "type": "TYPE_FIAT_US",
          "supportedRails": ["ACH", "FEDWIRE"],
          "accountType": "CHECKING"
        }
      }
    }
  ]
}

---

Request Fields

1. Main Counterparty Fields

Field	Type	Required	Description	Example
customerId	string	Yes	Customer ID who owns this counterparty.	"cust_12345"
description	string	No	Counterparty description.	"Primary electronics supplier"

2. Profile Object

Field	Type	Required	Description	Example
name	string	Yes	Legal name.	"Tech Supplies Corp"
email	string	No	Contact email.	"[email protected]"
phoneNumber	string	No	Contact phone.	"[phone]"
taxNumber	string	No	Tax ID number.	"TAX-US-12345"
dateOfBirth	string	No	Date of birth/incorporation.	"1985-05-15T00:00:00Z"
website	string	No	Company website.	"https://techsupplies.com"
lastname	string	No	Last name (individuals).	"Smith"

3. Address Object

Field	Type	Required	Description	Example
addressLine1	string	Yes	Primary address, 30 symbols max, no special characters	"123 Main Street"
addressLine2	string	No	Suite/floor, 30 symbols max, no special characters	"Suite 500"
addressLine3	string	No	Additional info, 30 symbols max, no special characters	"Building B"
city	string	Yes	City, no special characters	"New York"
stateIso	string	Yes	State code.	"NY"
countryIso	string	Yes	Country code.	"US"
postalCode	string	Yes	Postal code.	"10001"
unitNumber	string	No	Unit number.	"5A"

4. Additional Info Object

Field	Type	Required	Description	Allowed Values	Example
type	string	Yes	Legal structure.	INDIVIDUAL, CORPORATION	"CORPORATION"
businessLine	string	Yes	Industry type.	PLB_AUTOMOTIVE, PLB_RETAIL, etc.	"PLB_HIGH_TECH_SOFTWARE_TELECOMS"
relationship	string	Yes	Business relationship.	PRC_SUPPLIER, PRC_CUSTOMER, etc.	"PRC_SUPPLIER"

5. Accounts Array

Array of bank/crypto accounts for the counterparty.

Field	Type	Required	Description	Example
currencyIso	string	Yes	Currency code (ISO 4217).	"USD"

Bank Account (Traditional) Required

Field	Type	Description
accounts[].currencyCode	string	Currency ISO code, e.g. USD, EUR, AED
accounts[].bank.name	string	Receiving bank's name (fewer than 35 characters)
accounts[].bank.address.addressLine1	string	Bank address — no special characters, accents, or leading/trailing spaces
accounts[].bank.address.city	string	Fewer than 21 characters
accounts[].bank.address.countryIso	string	Two-letter ISO code
accounts[].bank.address.stateIso	string	Same US/region rule as profile.address.stateIso
accounts[].bank.address.postalCode	string	Same US ZIP rule as profile.address.postalCode
accounts[].fiat.number	string	Account number/IBAN — must be the correct length and country code if an IBAN
accounts[].fiat.additionalInformation.type	string	Must name the specific currency, e.g. TYPE_FIAT_US — can't be the generic TYPE_FIAT
accounts[].fiat.additionalInformation.supportedRails	array	Exactly one rail, e.g. ["SWIFT"]

Conditionally required

Field	Type	Description
accounts[].fiat.swift	string	Mandatory for SWIFT beneficiary accounts
accounts[].fiat.routingNumber	string	Mandatory for domestic USA beneficiary accounts

Crypto Account

Required

Field	Type	Description
accounts[].currencyCode	string	Asset + network in one value, e.g. USDT_ERC20, USDT_TRC20
accounts[].crypto.address	string	Wallet address
accounts[].crypto.additionalInformation.walletType	string	e.g. CPW_INSTITUTION, CPW_UNKNOWN
accounts[].crypto.additionalInformation.type	string	TYPE_CRYPTO
accounts[].crypto.additionalInformation.supportedRails	array	["CRYPTO"]

Conditionally required

Field	Type	Description
accounts[].bank.name	string	Required when walletType is CPW_INSTITUTION — identifies the custodian institution behind the wallet
accounts[].bank.address	object	Required when walletType is CPW_INSTITUTION, same address sub-fields as fiat accounts above

Fiat Account (Detailed)

Field	Type	Required	Description	Example
fiat.number	string	Yes	Bank account number or IBAN	"987654321"
fiat.routingNumber	string	No	Bank's routing number.	"021000021"
fiat.swift	string	No	SWIFT code.	"CHASUS33"
fiat.ifsc	string	No	IFSC code (India).	"SBIN0000001"
fiat.sortCode	string	No	Sort code (UK).	"40-30-20"
fiat.additionalInformation.accountType	string	No	Account type.	CHECKING, SAVING

---

Response (200 OK)

Returns the created counterparty with system-generated IDs and timestamps.

Example Response:

json

{
  "item": {
    "id": "cp_12345",
    "customerId": "cust_12345",
    "description": "Primary electronics supplier",
    "profile": {
      "name": "Tech Supplies Corp",
      "email": "[email protected]",
      "phoneNumber": "[phone]",
      "taxNumber": "TAX-US-12345",
      "dateOfBirth": "1985-05-15T00:00:00Z",
      "address": {
        "addressLine1": "123 Main Street",
        "addressLine2": "Suite 500",
        "addressLine3": "Building B",
        "city": "New York",
        "stateIso": "NY",
        "countryIso": "US",
        "postalCode": "10001",
        "unitNumber": "5A"
      },
      "website": "https://techsupplies.com",
      "additionalInfo": {
        "type": "CORPORATION",
        "businessLine": "PLB_HIGH_TECH_SOFTWARE_TELECOMS",
        "relationship": "PRC_SUPPLIER"
      },
      "lastname": "Smith"
    },
    "accounts": [
      {
        "id": "acc_67890",
        "currencyIso": "USD",
        "status": "NEW",
        "bank": {
          "name": "Chase Bank",
          "number": "123456789",
          "address": {
            "addressLine1": "456 Bank Street",
            "city": "New York",
            "stateIso": "NY",
            "countryIso": "US",
            "postalCode": "10002"
          },
          "routingNumber": "021000021"
        },
        "fiat": {
          "number": "987654321",
          "routingNumber": "021000021",
          "additionalInformation": {
            "type": "TYPE_FIAT_US",
            "supportedRails": ["ACH", "FEDWIRE"],
            "accountType": "CHECKING"
          }
        }
      }
    ],
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-15T10:30:00Z",
    "customerName": "John Doe"
  }
}

---

Response Fields

Field	Type	Description	Example
item.id	string	System-generated counterparty ID.	"cp_12345"
item.accounts[].id	string	System-generated account ID.	"acc_67890"
item.accounts[].status	string	Account status.	NEW, ACCEPT, REJECT
item.createdAt	string	Creation timestamp.	"2024-01-15T10:30:00Z"
item.updatedAt	string	Last update timestamp.	"2024-01-15T10:30:00Z"
item.customerName	string	Customer name (auto-populated).	"John Doe"

Error Responses

1. Missing Required Fields:

   json

   { "error": "Missing required field: profile.name" }

2. Invalid Customer:

   json

   { "error": "Customer not found: cust_99999" }

3. Validation Error:

   json

   { "error": "Invalid address format" }

---

Notes

• Account Verification: New accounts start with NEW status and require verification
• Currency Support: Multiple accounts with different currencies can be added
• KYC Compliance: Complete profile information improves verification success
• A counterparty can hold multiple accounts across different currencies.

Supported Payment Rails:

• Traditional: ACH, FEDWIRE, SWIFT, SEPA_CT , FPS, CHAPS, UAEFTS
• Crypto: CRYPTO

Examples

Real request

{
    "profile": {
        "website": "sdfsd.com",
        "phoneNumber": "[phone]",
        "address": {
            "city": "Test",
            "stateIso": "Test",
            "countryIso": "AI",
            "postalCode": "Test",
            "addressLine1": "Test"
        },
        "name": "Test Recipient",
        "additionalInfo": {
            "type": "CORPORATION"
        },
        "email": "[email protected]"
    },
    "customerId": "D0uCaCN-MwtQ-lqaTXgJ4IGRM",
    "description": "saddadad",
    "accounts": [
        {
            "currencyCode": "EUR",
            "bank": {
                "address": {
                    "addressLine1": "456 Park Avenue",
                    "city": "New York",
                    "countryIso": "US",
                    "postalCode": "10022",
                    "stateIso": "NY"
                },
                "name": "Bank of America",
                "number": "161465165651",
                "routingNumber": null
            },
            "fiat": {
                "ifsc": "SBIN0001234",
                "name": "EUR 0",
                "number": "9876543210",
                "routingNumber": "121000358",
                "sortCode": "65265",
                "swift": "BOFAUS3N",
                "transitNumber": "121000358",
                "additionalInformation": {
                    "type": "TYPE_FIAT_EU",
                    "accountType": "CHECKING",
                    "supportedRails": [
                        "SEPA_CT"
                    ],
                    "intermediary": {
                        "type": "",
                        "bank": {
                            "name": null,
                            "number": "",
                            "routingNumber": "",
                            "address": {
                                "addressLine1": "",
                                "addressLine2": "",
                                "addressLine3": null,
                                "city": "",
                                "stateIso": "",
                                "countryIso": "",
                                "postalCode": "",
                                "unitNumber": null
                            }
                        }
                    }
                }
            }
        }
    ]
}

Real response

{
    "item": {
        "counterpartyId": "D41dltf-W6r7-MEOCYDRBddho",
        "customerId": "D0uCaCN-MwtQ-lqaTXgJ4IGRM",
        "description": "saddadad",
        "profile": {
            "name": "Test Recipient",
            "email": "[email protected]",
            "phoneNumber": "[phone]",
            "taxNumber": "",
            "dateOfBirth": "1970-01-01T00:00:00Z",
            "address": {
                "addressLine1": "Test",
                "addressLine2": "",
                "addressLine3": "",
                "city": "Test",
                "stateIso": "Test",
                "countryIso": "AI",
                "postalCode": "Test",
                "unitNumber": ""
            },
            "website": "sdfsd.com",
            "additionalInfo": {
                "type": "CORPORATION",
                "businessLine": "PLB_ARTS_AND_ANTIQUES",
                "relationship": "PRC_SPOUSE"
            },
            "lastname": ""
        },
        "accounts": [
            {
                "accountId": "ECrSuzKfJsCr",
                "currencyCode": "EUR",
                "status": "MODERATION",
                "bank": {
                    "name": "Bank of America",
                    "number": "161465165651",
                    "address": {
                        "addressLine1": "456 Park Avenue",
                        "addressLine2": "",
                        "addressLine3": "",
                        "city": "New York",
                        "stateIso": "NY",
                        "countryIso": "US",
                        "postalCode": "10022",
                        "unitNumber": ""
                    }
                },
                "fiat": {
                    "number": "9876543210",
                    "ifsc": "SBIN0001234",
                    "swift": "BOFAUS3N",
                    "sortCode": "65265",
                    "name": "EUR 0",
                    "transitNumber": "121000358",
                    "routingNumber": "121000358",
                    "additionalInformation": {
                        "type": "TYPE_FIAT_EU",
                        "supportedRails": [
                            "SEPA_CT"
                        ],
                        "intermediary": {
                            "type": "TYPE_CRYPTO",
                            "bank": {
                                "number": "",
                                "address": {
                                    "addressLine1": "",
                                    "addressLine2": "",
                                    "addressLine3": "",
                                    "city": "",
                                    "stateIso": "",
                                    "countryIso": "",
                                    "postalCode": "",
                                    "unitNumber": ""
                                },
                                "routingNumber": ""
                            }
                        },
                        "accountType": "CHECKING"
                    },
                    "accountNumberType": "ANT_NOTSET",
                    "transitNumberCode": "TNC_NOTSET"
                }
            }
        ],
        "createdAt": "2025-11-09T06:18:46Z",
        "updatedAt": "2025-11-09T06:18:46Z",
        "customerName": ""
    }
}

Account fields by currency and rail

USD — FEDWIRE

Required

Field	Type	Description
routingNumber	string	US ABA routing number
additionalInformation.accountType	string	e.g. CHECKING
additionalInformation.type	string	Set to TYPE_FIAT_US for USD accounts
additionalInformation.supportedRails	array	Contains FEDWIRE

Optional

Field	Type	Description
additionalInformation.intermediary	object
swift, sortCode, ifsc, transitNumber	string

USD — SWIFT

Required

Field	Type	Description
swift	string	BIC/SWIFT code — mandatory for SWIFT beneficiary accounts
additionalInformation.type	string	Set to TYPE_FIAT_US for USD accounts
additionalInformation.supportedRails	array	Contains SWIFT
additionalInformation.accountType	string
additionalInformation.intermediary	object
routingNumber	string

Optional

Field	Type	Description
bank.number	string
sortCode, ifsc, transitNumber	string

EUR — SEPA_CT

Required

Field	Type	Description
number	string	IBAN — must be the correct length and country code
swift	string	Receiving bank's BIC/SWIFT code
additionalInformation.type	string	Set to TYPE_FIAT_EU for EUR accounts
additionalInformation.supportedRails	array	Contains SEPA_CT
additionalInformation.accountType	string
additionalInformation.intermediary	object

Optional

Field	Type	Description
bank.number	string
routingNumber, sortCode, ifsc, transitNumber	string

GBP — FPS

Required

Field	Type	Description
sortCode	string	UK sort code
routingNumber	string	Mirrors sortCode in the reference example
additionalInformation.accountType	string	e.g. CHECKING
additionalInformation.type	string	Set to TYPE_FIAT_GB for GBP accounts
additionalInformation.supportedRails	array	Contains FPS

Optional

Field	Type	Description
swift, ifsc, transitNumber	string
bank.number	string
additionalInformation.intermediary	object

GBP — SWIFT

Required

Field	Type	Description
number	string	IBAN
swift	string	Receiving bank's BIC/SWIFT code
additionalInformation.accountType	string	e.g. CHECKING
additionalInformation.type	string	Set to TYPE_FIAT_GB for GBP accounts
additionalInformation.supportedRails	array	Contains SWIFT

Optional

Field	Type	Description
sortCode, routingNumber, ifsc, transitNumber	string
bank.number	string
name, fiat.name	string
additionalInformation.intermediary	object

GBP — CHAPS

Required

Field	Type	Description
sortCode	string	UK sort code
additionalInformation.accountType	string	e.g. CHECKING
additionalInformation.type	string	Set to TYPE_FIAT_GB for GBP accounts
additionalInformation.supportedRails	array	Contains CHAPS

Optional

Field	Type	Description
swift, routingNumber, ifsc, transitNumber	string
bank.number	string
name	string

AED — UAEFTS

Required

Field	Type	Description
number	string	IBAN
swift	string	Receiving bank's BIC/SWIFT code
additionalInformation.accountType	string	e.g. CHECKING
additionalInformation.type	string	Set to TYPE_FIAT_AE for AED accounts
additionalInformation.supportedRails	array	Contains UAEFTS
additionalInformation.intermediary	object

Optional

Field	Type	Description
bank.number	string
routingNumber, sortCode, ifsc, transitNumber	string

Crypto accounts

Required

Field	Type	Description
currencyCode	string	Encodes both asset and network in one value, e.g. USDT_TRC20, USDT_ERC20 — there's no separate "network" field
crypto.address	string	Wallet address
crypto.additionalInformation.walletType	string	Wallet classification — confirmed values: CPW_INSTITUTION, CPW_UNKNOWN, CPW_OTHER
crypto.additionalInformation.type	string	Set to TYPE_CRYPTO
crypto.additionalInformation.supportedRails	array	Contains CRYPTO

Conditionally required

Field	Type	Description
bank.name	string	Required when walletType is CPW_INSTITUTION — the name of the custodian institution
bank.address	object	Required when walletType is CPW_INSTITUTION — the custodian's address, same sub-fields as fiat accounts