> ## Documentation Index
> Fetch the complete documentation index at: https://diameterpay.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a New Counterparty Payment Recipient

> POST /v1/counter-parties — Register a new payment recipient for an end user. Pre-creating counterparties avoids delays at wire initiation time.

Creating a counterparty registers a payment recipient — either an individual or an organization — against an end user's profile. By pre-creating counterparties ahead of wire initiation, you eliminate validation delays at the point of payment and ensure bank-partner onboarding is completed in advance. Each counterparty is scoped to a single end user and can be onboarded to one or more supported bank partners.

## Endpoint

```
POST /v1/counter-parties
```

**Required scope:** `com.diameterpay.api/counter-parties.write`

## Request Headers

**Authorization** `string` *required*

Bearer token obtained from your OAuth2 token endpoint. Format: `Bearer {access_token}`

**x-idempotency-key** `string` *required*

A UUID v4 string that uniquely identifies this request. Replaying the same key within the idempotency window returns the original response without creating a duplicate.

## Request Body

**type** `string` *required*

The counterparty classification. Must be one of:

* `ORGANIZATION` — a business or legal entity
* `INDIVIDUAL` — a natural person

**endUserId** `string` *required*

UUID of the end user who owns this counterparty.

**bankPartner** `string` *required*

The bank partner to onboard this counterparty with initially. Must be one of:

* `PORTAGE`
* `SLOVAK_SAVINGS_BANK`

**fullName** `string`

Full legal name of the counterparty. **Required when `type` is `ORGANIZATION`.**

**firstName** `string`

First name of the counterparty. **Required when `type` is `INDIVIDUAL`.**

**lastName** `string`

Last name of the counterparty. **Required when `type` is `INDIVIDUAL`.**

**middleName** `string`

Middle name of the counterparty. Optional — applicable only when `type` is `INDIVIDUAL`.

**wireInformation** `object` *required*

Bank account and routing details used to execute wire transfers to this counterparty.

**wireInformation fields**

**bankName** `string` *required*

The name of the counterparty's receiving bank.

**accountNumber** `string` *required*

The counterparty's bank account number.

**routingNumberType** `string` *required*

The type of routing identifier. Must be one of:

* `ABA` — American Bankers Association routing number (domestic)
* `BIC` — Business Identifier Code (international / SWIFT)

**routingNumber** `string` *required*

The ABA routing number or BIC/SWIFT code for the receiving bank.

**address** `object` *required*

The counterparty's postal address associated with their bank account.

**address fields**

**addressType** `string` *required*

Standardized address type code. Must be one of:

* `ADDR` — postal address
* `PBOX` — PO box
* `HOME` — residential address
* `BIZZ` — business address
* `MLTO` — mailing-to address
* `DLVY` — delivery address

**country** `string` *required*

ISO 3166-1 alpha-2 country code (e.g. `US`, `GB`, `DE`).

**postalCode** `string` *required*

Postal or ZIP code for the address.

**townName** `string` *required*

City or town name.

**streetName** `string` *required*

Street name (excluding building number).

**buildingNumber** `string`

Building or house number. Optional.

**countrySubdivision** `string`

State, province, or region code. Optional (e.g. `CA`, `NY`).

## Response

Returns **HTTP 201 Created** with a `CounterPartyOutput` object on success.

**id** `string`

UUID uniquely identifying this counterparty record.

**type** `string`

The counterparty type: `ORGANIZATION` or `INDIVIDUAL`.

**endUserId** `string`

UUID of the end user this counterparty belongs to.

**wireInformation** `object`

The wire transfer details provided at creation, including `bankName`, `accountNumber`, `routingNumberType`, `routingNumber`, and `address`.

**bankPartners** `array`

List of bank partner onboarding records for this counterparty.

**bankPartners item fields**

**bankPartner** `string`

The bank partner identifier: `PORTAGE` or `SLOVAK_SAVINGS_BANK`.

**status** `string`

Current onboarding status with the bank partner:

* `ACTIVE` — onboarded and ready to receive payments
* `BLOCKED` — onboarding blocked; contact support

**createdAt** `string`

ISO 8601 timestamp of when the counterparty was created.

**updatedAt** `string`

ISO 8601 timestamp of the most recent update to the counterparty record.

## Examples

### Create an Organization Counterparty

```bash cURL theme={null}
curl --request POST \
  --url https://api.diameterpay.com/v1/counter-parties \
  --header "Authorization: Bearer {access_token}" \
  --header "x-idempotency-key: 550e8400-e29b-41d4-a716-446655440000" \
  --header "Content-Type: application/json" \
  --data '{
    "type": "ORGANIZATION",
    "endUserId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "bankPartner": "PORTAGE",
    "fullName": "Acme Corp LLC",
    "wireInformation": {
      "bankName": "First National Bank",
      "accountNumber": "123456789",
      "routingNumberType": "ABA",
      "routingNumber": "021000021",
      "address": {
        "addressType": "BIZZ",
        "country": "US",
        "postalCode": "10001",
        "townName": "New York",
        "streetName": "5th Avenue",
        "buildingNumber": "350",
        "countrySubdivision": "NY"
      }
    }
  }'
```

### Create an Individual Counterparty

```bash cURL theme={null}
curl --request POST \
  --url https://api.diameterpay.com/v1/counter-parties \
  --header "Authorization: Bearer {access_token}" \
  --header "x-idempotency-key: 7c9e6679-7425-40de-944b-e07fc1f90ae7" \
  --header "Content-Type: application/json" \
  --data '{
    "type": "INDIVIDUAL",
    "endUserId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "bankPartner": "SLOVAK_SAVINGS_BANK",
    "firstName": "Jane",
    "middleName": "Marie",
    "lastName": "Doe",
    "wireInformation": {
      "bankName": "City Bank International",
      "accountNumber": "987654321",
      "routingNumberType": "BIC",
      "routingNumber": "CITIUS33XXX",
      "address": {
        "addressType": "HOME",
        "country": "US",
        "postalCode": "94105",
        "townName": "San Francisco",
        "streetName": "Market Street",
        "buildingNumber": "101",
        "countrySubdivision": "CA"
      }
    }
  }'
```

### Response

```json theme={null}
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "type": "INDIVIDUAL",
  "endUserId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "wireInformation": {
    "bankName": "City Bank International",
    "accountNumber": "987654321",
    "routingNumberType": "BIC",
    "routingNumber": "CITIUS33XXX",
    "address": {
      "addressType": "HOME",
      "country": "US",
      "postalCode": "94105",
      "townName": "San Francisco",
      "streetName": "Market Street",
      "buildingNumber": "101",
      "countrySubdivision": "CA"
    }
  },
  "bankPartners": [
    {
      "bankPartner": "SLOVAK_SAVINGS_BANK",
      "status": "ACTIVE"
    }
  ],
  "createdAt": "2024-06-01T12:00:00.000Z",
  "updatedAt": "2024-06-01T12:00:00.000Z"
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.