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

# Counterparties

> Create and manage the recipients of your payouts.

A counterparty represents a payout recipient — a person or business you send funds to. Counterparties hold identity information. Payment routing details (bank account numbers, wallet addresses) are stored separately as payment details attached to the counterparty.

***

## The Counterparty object

<ResponseField name="id" type="string">
  Unique counterparty identifier.
</ResponseField>

<ResponseField name="entity_id" type="string">
  The entity this counterparty belongs to.
</ResponseField>

<ResponseField name="type" type="string">
  `individual` or `business`.
</ResponseField>

<ResponseField name="nickname" type="string">
  Display label. Defaults to full name for individuals and legal name for businesses.
</ResponseField>

<ResponseField name="status" type="string">
  `active` or `inactive`. Inactive counterparties cannot receive transfers.
</ResponseField>

<ResponseField name="profile" type="object">
  Identity details. Shape depends on `type`.

  <Expandable title="Individual profile fields">
    <ResponseField name="first_name" type="string">
      First name of the individual.
    </ResponseField>

    <ResponseField name="last_name" type="string">
      Last name of the individual.
    </ResponseField>

    <ResponseField name="relationship" type="string">
      Relationship to the sending entity. Allowed values: `vendor`, `supplier`, `customer`, `employee`.
    </ResponseField>

    <ResponseField name="email" type="string">
      Email address of the individual.
    </ResponseField>

    <ResponseField name="address" type="object">
      Physical address.

      <Expandable title="Address fields">
        <ResponseField name="line1" type="string">
          Street address line 1. Required.
        </ResponseField>

        <ResponseField name="line2" type="string">
          Street address line 2. Optional.
        </ResponseField>

        <ResponseField name="city" type="string">
          City. Required.
        </ResponseField>

        <ResponseField name="state_or_province" type="string">
          State or province. Optional.
        </ResponseField>

        <ResponseField name="postal_code" type="string">
          Postal or ZIP code. Optional.
        </ResponseField>

        <ResponseField name="country" type="string">
          ISO alpha-2 country code. Required.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="identification" type="array">
      Government-issued identification documents.

      <Expandable title="Identification fields">
        <ResponseField name="type" type="string">
          Document type. `P` = passport, `D` = driving licence, `N` = national ID.
        </ResponseField>

        <ResponseField name="number" type="string">
          Document number.
        </ResponseField>

        <ResponseField name="issuing_country" type="string">
          ISO alpha-2 country code of the issuing authority.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="phone" type="object">
      Phone contact details.

      <Expandable title="Phone fields">
        <ResponseField name="number" type="string">
          Phone number in E.164 format.
        </ResponseField>

        <ResponseField name="type" type="string">
          `mobile`, `work`, `home`, or `other`.
        </ResponseField>

        <ResponseField name="country" type="string">
          ISO alpha-2 country code.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>

  <Expandable title="Business profile fields">
    <ResponseField name="legal_name" type="string">
      Registered legal name of the business.
    </ResponseField>

    <ResponseField name="trading_name" type="string">
      Trading or DBA name, if different from the legal name. Optional.
    </ResponseField>

    <ResponseField name="relationship" type="string">
      Relationship to the sending entity. Allowed values: `vendor`, `supplier`, `customer`, `employee`.
    </ResponseField>

    <ResponseField name="email" type="string">
      Business contact email.
    </ResponseField>

    <ResponseField name="registered_address" type="object">
      Registered business address. Same shape as individual `address`.
    </ResponseField>

    <ResponseField name="identification" type="array">
      Business registration documents.

      <Expandable title="Identification fields">
        <ResponseField name="type" type="string">
          `L` = business registration number.
        </ResponseField>

        <ResponseField name="number" type="string">
          Registration number.
        </ResponseField>

        <ResponseField name="issuing_country" type="string">
          ISO alpha-2 country code of the registering authority.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="phone" type="object">
      Phone contact details. Same shape as individual `phone`.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="meta" type="object">
  Arbitrary key-value metadata.
</ResponseField>

<ResponseField name="created" type="number">
  Unix timestamp (milliseconds) when the counterparty was created.
</ResponseField>

<ResponseField name="updated" type="number">
  Unix timestamp (milliseconds) when the counterparty was last updated.
</ResponseField>

```json Example counterparty object theme={null}
{
  "id": "01KM37EZ0AYCVDXJ3WDHXPPSZ9",
  "entity_id": "01KBCFY3VB1XT0MC8VMZXME6RS",
  "type": "individual",
  "nickname": "Jane Smith",
  "status": "active",
  "profile": {
    "first_name": "Jane",
    "last_name": "Smith",
    "relationship": "vendor",
    "email": "jane.smith@example.com",
    "address": {
      "line1": "123 Main St",
      "city": "Austin",
      "state_or_province": "TX",
      "postal_code": "78701",
      "country": "US"
    }
  },
  "meta": {},
  "created": 1735725600000,
  "updated": 1735725600000
}
```

***

## Create a counterparty

`POST /counterparties`

Creates a counterparty of type `individual` or `business`. Attach payment details separately after creation.

### Request parameters

<ParamField body="type" type="string" required>
  `individual` or `business`.
</ParamField>

<ParamField body="entity_id" type="string" required>
  The entity this counterparty belongs to.
</ParamField>

<ParamField body="nickname" type="string">
  Display label. Defaults to first name + last name for individuals or legal name for businesses.
</ParamField>

<ParamField body="profile" type="object" required>
  Identity details. Required fields differ by `type`.

  <Expandable title="Individual profile">
    <ParamField body="first_name" type="string" required>
      First name.
    </ParamField>

    <ParamField body="last_name" type="string" required>
      Last name.
    </ParamField>

    <ParamField body="relationship" type="string" required>
      Relationship to the sending entity. One of: `vendor`, `supplier`, `customer`, `employee`.
    </ParamField>

    <ParamField body="email" type="string" required>
      Email address.
    </ParamField>

    <ParamField body="address" type="object" required>
      Physical address.

      <Expandable title="Address fields">
        <ParamField body="line1" type="string" required>
          Street address line 1.
        </ParamField>

        <ParamField body="line2" type="string">
          Street address line 2.
        </ParamField>

        <ParamField body="city" type="string" required>
          City.
        </ParamField>

        <ParamField body="state_or_province" type="string">
          State or province.
        </ParamField>

        <ParamField body="postal_code" type="string">
          Postal or ZIP code.
        </ParamField>

        <ParamField body="country" type="string" required>
          ISO alpha-2 country code (e.g. `US`, `GB`).
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="identification" type="array">
      Government-issued identification documents.

      <Expandable title="Identification fields">
        <ParamField body="type" type="string" required>
          Document type. `P` = passport, `D` = driving licence, `N` = national ID.
        </ParamField>

        <ParamField body="number" type="string" required>
          Document number.
        </ParamField>

        <ParamField body="issuing_country" type="string" required>
          ISO alpha-2 country code of the issuing authority.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="phone" type="object">
      Phone contact details.

      <Expandable title="Phone fields">
        <ParamField body="number" type="string" required>
          Phone number in E.164 format.
        </ParamField>

        <ParamField body="type" type="string" required>
          `mobile`, `work`, `home`, or `other`.
        </ParamField>

        <ParamField body="country" type="string" required>
          ISO alpha-2 country code.
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>

  <Expandable title="Business profile">
    <ParamField body="legal_name" type="string" required>
      Registered legal name of the business.
    </ParamField>

    <ParamField body="trading_name" type="string">
      Trading or DBA name, if different from the legal name.
    </ParamField>

    <ParamField body="relationship" type="string" required>
      Relationship to the sending entity. One of: `vendor`, `supplier`, `customer`, `employee`.
    </ParamField>

    <ParamField body="email" type="string" required>
      Business contact email.
    </ParamField>

    <ParamField body="registered_address" type="object" required>
      Registered business address. Same shape as individual `address`.
    </ParamField>

    <ParamField body="identification" type="array">
      Business registration documents.

      <Expandable title="Identification fields">
        <ParamField body="type" type="string" required>
          `L` = business registration number.
        </ParamField>

        <ParamField body="number" type="string" required>
          Registration number.
        </ParamField>

        <ParamField body="issuing_country" type="string" required>
          ISO alpha-2 country code of the registering authority.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="phone" type="object">
      Phone contact details. Same shape as individual `phone`.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="meta" type="object">
  Arbitrary key-value metadata. Keys and values must be strings.
</ParamField>

### Request

<CodeGroup>
  ```bash Individual theme={null}
  curl -X POST https://api.nuvion.dev/counterparties \
    -H "Authorization: Bearer $NUVION_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "type": "individual",
      "entity_id": "01KBCFY3VB1XT0MC8VMZXME6RS",
      "profile": {
        "first_name": "Jane",
        "last_name": "Smith",
        "relationship": "vendor",
        "email": "jane.smith@example.com",
        "address": {
          "line1": "123 Main St",
          "city": "Austin",
          "state_or_province": "TX",
          "postal_code": "78701",
          "country": "US"
        }
      }
    }'
  ```

  ```bash Business theme={null}
  curl -X POST https://api.nuvion.dev/counterparties \
    -H "Authorization: Bearer $NUVION_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "type": "business",
      "entity_id": "01KBCFY3VB1XT0MC8VMZXME6RS",
      "profile": {
        "legal_name": "Acme Corp Ltd",
        "relationship": "supplier",
        "email": "accounts@acmecorp.com",
        "registered_address": {
          "line1": "456 Business Ave",
          "city": "New York",
          "state_or_province": "NY",
          "postal_code": "10001",
          "country": "US"
        }
      }
    }'
  ```
</CodeGroup>

### Response

Returns the created [Counterparty object](#the-counterparty-object).

### Errors

| Code  | Description                                                                 |
| ----- | --------------------------------------------------------------------------- |
| `422` | Validation error — a required field is missing or a field value is invalid. |
| `422` | A counterparty with these details already exists for this entity.           |
| `409` | The specified `entity_id` was not found.                                    |

***

## List counterparties

`GET /counterparties`

Returns a paginated list of counterparties.

### Query parameters

<ParamField query="entity_id" type="string">
  Filter by entity. Required when authenticating with an API key.
</ParamField>

<ParamField query="type" type="string">
  Filter by counterparty type. `individual` or `business`.
</ParamField>

<ParamField query="status" type="string">
  Filter by status. `active` or `inactive`.
</ParamField>

<ParamField query="limit" type="integer">
  Number of results to return. Between 1 and 100. Defaults to `20`.
</ParamField>

<ParamField query="cursor" type="string">
  Pagination cursor returned in the previous response's `meta.pagination.next_cursor`.
</ParamField>

### Request

```bash theme={null}
curl "https://api.nuvion.dev/counterparties?entity_id=01KBCFY3VB1XT0MC8VMZXME6RS&status=active" \
  -H "Authorization: Bearer $NUVION_API_KEY"
```

### Response

```json theme={null}
{
  "data": [
    {
      "id": "01KM37EZ0AYCVDXJ3WDHXPPSZ9",
      "entity_id": "01KBCFY3VB1XT0MC8VMZXME6RS",
      "type": "individual",
      "nickname": "Jane Smith",
      "status": "active",
      "profile": {
        "first_name": "Jane",
        "last_name": "Smith",
        "relationship": "vendor",
        "email": "jane.smith@example.com",
        "address": {
          "line1": "123 Main St",
          "city": "Austin",
          "state_or_province": "TX",
          "postal_code": "78701",
          "country": "US"
        }
      },
      "meta": {},
      "created": 1735725600000,
      "updated": 1735725600000
    }
  ],
  "meta": {
    "pagination": {
      "has_more": false,
      "next_cursor": null
    }
  }
}
```

***

## Get a counterparty

`GET /counterparties/{counterparty_id}`

Retrieves a single counterparty by ID.

### Path parameters

<ParamField path="counterparty_id" type="string" required>
  The counterparty ID. 26-character ULID.
</ParamField>

### Query parameters

<ParamField query="entity_id" type="string">
  Required when authenticating with an API key.
</ParamField>

### Request

```bash theme={null}
curl "https://api.nuvion.dev/counterparties/01KM37EZ0AYCVDXJ3WDHXPPSZ9" \
  -H "Authorization: Bearer $NUVION_API_KEY"
```

### Response

Returns the [Counterparty object](#the-counterparty-object).

***

## Update a counterparty

`PATCH /counterparties/{counterparty_id}`

Partially updates a counterparty. Only the fields you provide are changed — omitted fields remain unchanged.

### Path parameters

<ParamField path="counterparty_id" type="string" required>
  The counterparty ID. 26-character ULID.
</ParamField>

### Request parameters

<ParamField body="entity_id" type="string">
  Required when authenticating with an API key.
</ParamField>

<ParamField body="nickname" type="string">
  Updated display label.
</ParamField>

<ParamField body="profile" type="object">
  Any subset of profile fields for the counterparty's type. Only provided fields are updated.
</ParamField>

### Request

```bash theme={null}
curl -X PATCH https://api.nuvion.dev/counterparties/01KM37EZ0AYCVDXJ3WDHXPPSZ9 \
  -H "Authorization: Bearer $NUVION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "entity_id": "01KBCFY3VB1XT0MC8VMZXME6RS",
    "profile": {
      "email": "jane.updated@example.com"
    }
  }'
```

### Response

Returns the updated [Counterparty object](#the-counterparty-object).

***

## List Counterparty Payment Details

To get the list of payment details associated with a counterparty, use the `GET /counterparties/{counterparty_id}/payment-details` endpoint.

<CodeGroup>
  ```bash Req theme={null}
  curl -X GET https://api.nuvion.dev/counterparties/01KM37EZ0AYCVDXJ3WDHXPPSZ9/payment-details \
    -H "Authorization: Bearer $NUVION_API_KEY" \
    -H "Content-Type: application/json" \
  ```
</CodeGroup>

## Deactivate a counterparty

`POST /counterparties/{counterparty_id}/deactivate`

Sets the counterparty's status to `inactive`. Deactivated counterparties cannot receive new transfers.

<Warning>
  Deactivation cannot be reversed via the API.
</Warning>

### Path parameters

<ParamField path="counterparty_id" type="string" required>
  The counterparty ID. 26-character ULID.
</ParamField>

### Request parameters

<ParamField body="entity_id" type="string">
  Required when authenticating with an API key.
</ParamField>

### Request

```bash theme={null}
curl -X POST "https://api.nuvion.dev/counterparties/01KM37EZ0AYCVDXJ3WDHXPPSZ9/deactivate" \
  -H "Authorization: Bearer $NUVION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "entity_id": "01KBCFY3VB1XT0MC8VMZXME6RS" }'
```

### Response

Returns the updated [Counterparty object](#the-counterparty-object) with `status: "inactive"`.

### Errors

| Code  | Description                           |
| ----- | ------------------------------------- |
| `409` | The counterparty is already inactive. |

***