# Create counterparty

**Endpoint**

`POST/v2/counterparty`

**Link**

{% embed url="<https://stagep.tst-apidmndelss.com/openapi/v2.html#/operations/Counterparties_Create>" %}

### **Request**

#### **Headers**

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

#### **Request Body**

**Required fields:** `customerId`, `profile.name`, `profile.address.addressLine1`

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)**

| Field                    | Type     | Required | Description          | Example        |
| ------------------------ | -------- | -------- | -------------------- | -------------- |
| **`bank.name`**          | `string` | **Yes**  | Bank name.           | `"Chase Bank"` |
| **`bank.number`**        | `string` | No       | Bank code.           | `"123456789"`  |
| **`bank.routingNumber`** | `string` | No       | Routing number (US). | `"021000021"`  |

**Crypto Account**

| Field                                             | Type     | Required | Description            | Example                        |
| ------------------------------------------------- | -------- | -------- | ---------------------- | ------------------------------ |
| **`crypto.address`**                              | `string` | **Yes**  | Crypto wallet address. | `"0x742..."`                   |
| **`crypto.additionalInformation.walletType`**     | `string` | **Yes**  | Wallet type.           | `CPW_INSTITUTION`, `CPW_OTHER` |
| **`crypto.additionalInformation.type`**           | `string` | **Yes**  | Account type.          | `TYPE_CRYPTO`                  |
| **`crypto.additionalInformation.supportedRails`** | `array`  | **Yes**  | Payment rails.         | `["CRYPTO"]`                   |

**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

**Supported Payment Rails**:

* **Traditional**: `ACH`, `FEDWIRE`, `SWIFT`, `SEPA_CT`
* **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": ""
    }
}
```


---

# Agent Instructions: 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:

```
GET https://docs.delos.financial/counterparties/create-counterparty.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.