> For the complete documentation index, see [llms.txt](https://docs.delos.financial/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.delos.financial/counterparties/create-counterparty.md). # 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** {% embed url="" %} ### **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": "contact@techsupplies.com", "phoneNumber": "+19876543210", "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. | `"contact@techsupplies.com"` | | **`phoneNumber`** | `string` | No | Contact phone. | `"+19876543210"` | | **`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": "contact@techsupplies.com", "phoneNumber": "+19876543210", "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** ```json { "profile": { "website": "sdfsd.com", "phoneNumber": "+11231232323", "address": { "city": "Test", "stateIso": "Test", "countryIso": "AI", "postalCode": "Test", "addressLine1": "Test" }, "name": "Test Recipient", "additionalInfo": { "type": "CORPORATION" }, "email": "test@test.com" }, "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** ```json { "item": { "counterpartyId": "D41dltf-W6r7-MEOCYDRBddho", "customerId": "D0uCaCN-MwtQ-lqaTXgJ4IGRM", "description": "saddadad", "profile": { "name": "Test Recipient", "email": "test@test.com", "phoneNumber": "+11231232323", "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 |
--- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.delos.financial/counterparties/create-counterparty.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.