> ## 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 and Manage Payment Counterparties

> Learn how to create, search, and manage counterparties for wire payments, including onboarding them to additional bank partners.

A counterparty in Diameter represents the recipient of a wire payment — the external bank account that will receive funds when your end user sends a transfer. Each counterparty is associated with a specific end user and a partner bank, and stores the routing details needed to execute the wire. Pre-creating counterparties before initiating payments lets Diameter run compliance checks in advance, reducing delays at the moment of transfer.

> [!TIP]
>
> Create counterparties ahead of time during user onboarding, not immediately before a payment. This gives Diameter time to screen the recipient and avoids compliance-related delays during time-sensitive transactions.

### Create a counterparty

Send a `POST` to `/v1/counter-parties` with the recipient's identity and bank routing details. Set `bankPartner` to the partner bank whose account will be used to originate the wire.

```bash cURL — Organization theme={null}
curl -X POST https://api.sandbox.diameterpay.com/v1/counter-parties \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "x-idempotency-key: 550e8400-e29b-41d4-a716-446655440020" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "ORGANIZATION",
    "fullName": "Acme Corporation",
    "endUserId": "END_USER_UUID",
    "bankPartner": "PORTAGE",
    "wireInformation": {
      "bankName": "Chase Bank",
      "accountNumber": "000123456789",
      "routingNumberType": "ABA",
      "routingNumber": "021000021",
      "address": {
        "addressType": "BIZZ",
        "country": "US",
        "postalCode": "10017",
        "townName": "New York",
        "streetName": "Park Avenue",
        "countrySubdivision": "NY",
        "buildingNumber": "270"
      }
    }
  }'
```

```bash cURL — Individual theme={null}
curl -X POST https://api.sandbox.diameterpay.com/v1/counter-parties \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "x-idempotency-key: 550e8400-e29b-41d4-a716-446655440021" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "INDIVIDUAL",
    "firstName": "John",
    "middleName": "Robert",
    "lastName": "Doe",
    "endUserId": "END_USER_UUID",
    "bankPartner": "PORTAGE",
    "wireInformation": {
      "bankName": "Wells Fargo",
      "accountNumber": "9876543210",
      "routingNumberType": "ABA",
      "routingNumber": "121000248",
      "address": {
        "addressType": "HOME",
        "country": "US",
        "postalCode": "94105",
        "townName": "San Francisco",
        "streetName": "Market Street",
        "countrySubdivision": "CA",
        "buildingNumber": "100"
      }
    }
  }'
```

```json Response theme={null}
{
  "id": "cp-6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  "type": "ORGANIZATION",
  "fullName": "Acme Corporation",
  "endUserId": "END_USER_UUID",
  "bankPartners": [
    {
      "bankPartner": "PORTAGE",
      "status": "ACTIVE"
    }
  ],
  "wireInformation": {
    "bankName": "Chase Bank",
    "accountNumber": "000123456789",
    "routingNumberType": "ABA",
    "routingNumber": "021000021"
  },
  "createdAt": "2024-01-15T11:00:00Z"
}
```

Save the `id` from the response — this is your `creditorId` when initiating wire payments.

**Identity fields by counterparty type:**

| Field | `ORGANIZATION` | `INDIVIDUAL` |
| - | - | - |
| `fullName` | ✅ Required | ❌ Not used |
| `firstName` | ❌ Not used | ✅ Required |
| `lastName` | ❌ Not used | ✅ Required |
| `middleName` | ❌ Not used | Optional |

**Routing number types:**

| Type | Use case | Field value |
| - | - | - |
| `ABA` | Domestic US wire (US routing number) | 9-digit ABA routing number |
| `BIC` | International wire (SWIFT code) | 8 or 11-character BIC/SWIFT code |

> [!NOTE]
>
> For `BIC`-routed counterparties, Diameter automatically resolves the intermediary routing number required by the correspondent banking network. You do not need to provide it manually.

### Search counterparties

Retrieve counterparties associated with a specific end user using query parameters. Combine filters to narrow results.

```bash cURL theme={null}
curl -X GET "https://api.sandbox.diameterpay.com/v1/counter-parties?endUserId=END_USER_UUID&name=Acme&type=ORGANIZATION" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

```json Response theme={null}
{
  "counterParties": [
    {
      "id": "cp-6ba7b810-9dad-11d1-80b4-00c04fd430c8",
      "type": "ORGANIZATION",
      "fullName": "Acme Corporation",
      "endUserId": "END_USER_UUID",
      "bankPartners": [
        {
          "bankPartner": "PORTAGE",
          "status": "ACTIVE"
        }
      ]
    }
  ],
  "total": 1
}
```

Supported query parameters:

| Parameter | Description |
| - | - |
| `endUserId` | Filter by end user UUID |
| `name` | Partial name search (organization or individual) |
| `type` | `ORGANIZATION` or `INDIVIDUAL` |

### Onboard a counterparty to a second bank

If your end user is onboarded at multiple partner banks, you need to onboard their counterparties at each bank too. Send a `PATCH` to `/v1/counter-parties/{id}/onboard` to add a bank partner without recreating the entire counterparty record.

```bash cURL theme={null}
curl -X PATCH https://api.sandbox.diameterpay.com/v1/counter-parties/COUNTERPARTY_ID/onboard \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "x-idempotency-key: 550e8400-e29b-41d4-a716-446655440022" \
  -H "Content-Type: application/json" \
  -d '{
    "bankPartner": "SLOVAK_SAVINGS_BANK"
  }'
```

```json Response theme={null}
{
  "id": "cp-6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  "bankPartners": [
    {
      "bankPartner": "PORTAGE",
      "status": "ACTIVE"
    },
    {
      "bankPartner": "SLOVAK_SAVINGS_BANK",
      "status": "PENDING"
    }
  ]
}
```

The new bank partner entry starts in `PENDING` status while the bank runs its own compliance checks. The `COUNTERPARTY_CREATED` webhook fires when the counterparty becomes active at the new bank.

***

## Using inline counterparties

If you prefer not to pre-create a counterparty record, you can pass the full creditor details directly inside the payment request body instead of a `creditorId`. This is useful for one-off payments to recipients you don't need to store.

> [!WARNING]
>
> Inline counterparties skip the advance compliance pre-screening that a pre-created counterparty goes through. This can delay the payment if the recipient triggers a manual review. For recurring payments to the same recipient, always pre-create the counterparty.


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