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

> A counterparty represents an external person or business that your entities send money to or receive money from. Counterparties are scoped to an entity and must be created before they can be used in a transfer.

A counterparty is a named destination or source for money movement. Before initiating a payout, your entity must have a counterparty on file — think of it as a saved recipient record. Counterparties are scoped to a specific entity via `entity_id` and can be either individuals or businesses. Payment details (bank account numbers, routing info) are attached separately and linked to a counterparty.

***

## Create a counterparty

<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",
      "nickname": "Jane Smith",
      "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"
        },
        "phone": {
          "number": "+15125550142",
          "type": "mobile",
          "country": "US"
        },
        "identification": [
          {
            "type": "P",
            "number": "P123456789",
            "issuing_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",
      "nickname": "Acme Corp",
      "profile": {
        "legal_name": "Acme Corp Ltd",
        "trading_name": "Acme Corp",
        "relationship": "supplier",
        "email": "accounts@acmecorp.com",
        "registered_address": {
          "line1": "456 Business Ave",
          "city": "New York",
          "state_or_province": "NY",
          "postal_code": "10001",
          "country": "US"
        },
        "phone": {
          "number": "+12125550199",
          "type": "work",
          "country": "US"
        },
        "identification": [
          {
            "type": "L",
            "number": "EIN-47-9876543",
            "issuing_country": "US"
          }
        ]
      }
    }'
  ```
</CodeGroup>

### Request parameters

<ParamField body="type" type="string" required>
  The counterparty type. One of `individual` or `business`.
</ParamField>

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

<ParamField body="nickname" type="string">
  A human-readable label for the counterparty. Defaults to `first_name + last_name` for individuals, or `legal_name` for businesses. Max 255 characters.
</ParamField>

<ParamField body="profile" type="object" required>
  Profile fields differ based on `type`.

  <Expandable title="Individual profile fields">
    <ParamField body="first_name" type="string" required>
      First name of the individual. 1–100 characters.
    </ParamField>

    <ParamField body="last_name" type="string" required>
      Last name of the individual. 1–100 characters.
    </ParamField>

    <ParamField body="relationship" type="string" required>
      The relationship of this counterparty to the entity. e.g. `vendor`, `employee`, `contractor`.
    </ParamField>

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

    <ParamField body="address" type="object" required>
      Address of the individual.

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

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

        <ParamField body="city" type="string" required>
          City. 1–100 characters.
        </ParamField>

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

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

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

    <ParamField body="identification" type="array">
      Identity documents for the individual.

      <Expandable title="identification item fields">
        <ParamField body="type" type="string" required>
          Document type. One of `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 3166-1 alpha-2 country code of the issuing authority.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="phone" type="object">
      Phone number for the individual.

      <Expandable title="phone fields">
        <ParamField body="number" type="string" required>
          Phone number including country code. e.g. `+15125550142`.
        </ParamField>

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

        <ParamField body="country" type="string" required>
          ISO 3166-1 alpha-2 country code for the phone number.
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>

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

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

    <ParamField body="relationship" type="string" required>
      The relationship of this business counterparty to the entity. e.g. `supplier`, `partner`, `customer`.
    </ParamField>

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

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

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

      <Expandable title="identification item fields">
        <ParamField body="type" type="string" required>
          Always `L` for business identification number.
        </ParamField>

        <ParamField body="number" type="string" required>
          Business registration or tax identification number.
        </ParamField>

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

    <ParamField body="phone" type="object">
      Business phone number. Same structure as the individual `phone` object.
    </ParamField>
  </Expandable>
</ParamField>

***

## The counterparty object

<ResponseField name="id" type="string">
  Unique identifier for the counterparty. ULID format.
</ResponseField>

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

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

<ResponseField name="nickname" type="string">
  Human-readable label for the counterparty.
</ResponseField>

<ResponseField name="status" type="string">
  Current status of the counterparty. Either `active` or `inactive`. Inactive counterparties cannot be used in transfers.
</ResponseField>

<ResponseField name="profile" type="object">
  Profile details for the counterparty. 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 of the counterparty to the entity.</ResponseField>
    <ResponseField name="email" type="string">Email address.</ResponseField>
    <ResponseField name="address" type="object">Address of the individual, including `line1`, `city`, and `country`.</ResponseField>
    <ResponseField name="identification" type="array">Identity documents. Each item has `type`, `number`, and `issuing_country`.</ResponseField>
    <ResponseField name="phone" type="object">Phone number details, including `number`, `type`, and `country`.</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 name or DBA, if different from legal name.</ResponseField>
    <ResponseField name="relationship" type="string">Relationship of the business counterparty to the entity.</ResponseField>
    <ResponseField name="email" type="string">Business contact email address.</ResponseField>
    <ResponseField name="registered_address" type="object">Registered address of the business.</ResponseField>
    <ResponseField name="identification" type="array">Business identification documents.</ResponseField>
    <ResponseField name="phone" type="object">Business phone number details.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="meta" type="object">
  Additional metadata attached to the counterparty.
</ResponseField>

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

<ResponseField name="updated" type="number">
  Unix timestamp in milliseconds of the last update to the counterparty.
</ResponseField>

```json 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"
    },
    "identification": [
      {
        "type": "P",
        "number": "P123456789",
        "issuing_country": "US"
      }
    ],
    "phone": {
      "number": "+15125550142",
      "type": "mobile",
      "country": "US"
    }
  },
  "meta": {},
  "created": 1740000000000,
  "updated": 1740000000000
}
```

***

## List counterparties

Returns a paginated list of counterparties for the given entity.

<Note>
  `entity_id` is required when authenticating with an API key. It is inferred from the token when using entity-scoped access.
</Note>

<CodeGroup>
  ```bash curl theme={null}
  curl -G https://api.nuvion.dev/counterparties \
    -H "Authorization: Bearer $NUVION_API_KEY" \
    -d entity_id=01KBCFY3VB1XT0MC8VMZXME6RS \
    -d status=active \
    -d limit=20
  ```
</CodeGroup>

### Query parameters

<ParamField query="entity_id" type="string" required>
  Filter counterparties by entity. Required when using API key authentication.
</ParamField>

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

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

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

<ParamField query="cursor" type="string">
  Cursor from the previous response's `meta.pagination.next_cursor` to fetch the next page.
</ParamField>

### 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": 1740000000000,
      "updated": 1740000000000
    }
  ],
  "meta": {
    "pagination": {
      "has_more": false,
      "next_cursor": null
    }
  }
}
```

***

## Get a counterparty

Retrieves a single counterparty by ID.

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

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

***

## Update a counterparty

Partially updates an existing counterparty. Only the fields included in the request body are changed — omitted fields remain unchanged.

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

### Request parameters

<ParamField body="entity_id" type="string">
  Reassign or confirm the entity scope for this counterparty.
</ParamField>

<ParamField body="nickname" type="string">
  Update the display label for this counterparty. Max 255 characters.
</ParamField>

<ParamField body="profile" type="object">
  Any subset of profile fields to update. Fields not included are not changed. Refer to the [profile fields](#request-parameters) in the create section for the full list of accepted fields.
</ParamField>

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

***

## Deactivate a counterparty

Deactivates a counterparty, setting its status to `inactive`.

<Warning>
  Deactivated counterparties cannot receive transfers. This action cannot be reversed via the API — contact Nuvion support to reactivate a counterparty.
</Warning>

<CodeGroup>
  ```bash curl 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"
    }'
  ```
</CodeGroup>

Returns the updated counterparty object with `status: "inactive"`. Returns `409 Conflict` if the counterparty is already inactive.

***

## What's next

<CardGroup cols={2}>
  <Card title="Send a Payout" icon="arrow-up-right" href="/guides/send-a-payout">
    Initiate a transfer to a counterparty using their saved payment details.
  </Card>

  <Card title="Counterparties API reference" icon="code" href="/api-reference/counterparties">
    Full endpoint documentation for creating and managing counterparties.
  </Card>
</CardGroup>