> ## 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.

# Onboard a Counterparty to an Additional Bank Partner

> PATCH /v1/counter-parties/{id}/onboard — Register an existing counterparty with an additional bank partner. Requires com.diameterpay.api/counter-parties.write scope.

After a counterparty is created, you can register them with additional bank partners using this endpoint. This is necessary when a wire transfer must be routed through a bank partner the counterparty has not yet been onboarded to. Once onboarding completes successfully, the new bank partner will appear in the counterparty's `bankPartners` array with an `ACTIVE` status.

## Endpoint

```
PATCH /v1/counter-parties/{id}/onboard
```

**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 triggering a duplicate onboarding attempt.

## Path Parameters

**id** `string` *required*

The UUID of the counterparty to onboard with an additional bank partner.

## Request Body

**bankPartner** `string` *required*

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

* `PORTAGE`
* `SLOVAK_SAVINGS_BANK`

The specified bank partner must not already be present in the counterparty's `bankPartners` array.

## Response

Returns **HTTP 200 OK** with the updated `CounterPartyOutput` object, reflecting the newly added bank partner entry in `bankPartners`.

**id** `string`

UUID uniquely identifying the 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 for this counterparty.

**bankPartners** `array`

Updated list of bank partner onboarding records, now including the newly registered bank partner.

**bankPartners item fields**

**bankPartner** `string`

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

**status** `string`

Current onboarding status with this 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, reflecting the new onboarding.

## Example

```bash cURL theme={null}
curl --request PATCH \
  --url https://api.diameterpay.com/v1/counter-parties/a1b2c3d4-e5f6-7890-abcd-ef1234567890/onboard \
  --header "Authorization: Bearer {access_token}" \
  --header "x-idempotency-key: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d" \
  --header "Content-Type: application/json" \
  --data '{
    "bankPartner": "PORTAGE"
  }'
```

### Response

```json theme={null}
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "type": "INDIVIDUAL",
  "endUserId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "firstName": "Jane",
  "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"
    }
  },
  "bankPartners": [
    {
      "bankPartner": "SLOVAK_SAVINGS_BANK",
      "status": "ACTIVE"
    },
    {
      "bankPartner": "PORTAGE",
      "status": "ACTIVE"
    }
  ],
  "createdAt": "2024-06-01T12:00:00.000Z",
  "updatedAt": "2024-06-02T09:30:00.000Z"
}
```


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