Counterparties

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

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"
        }
      ]
    }
  }'

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"
        }
      ]
    }
  }'

Request parameters

string

required

The counterparty type. One of individual or business.

string

required

The ULID of the entity this counterparty belongs to.

string

A human-readable label for the counterparty. Defaults to first_name + last_name for individuals, or legal_name for businesses. Max 255 characters.

object

required

Profile fields differ based on type.

Show Individual profile fields

string

required

First name of the individual. 1–100 characters.

string

required

Last name of the individual. 1–100 characters.

string

required

The relationship of this counterparty to the entity. e.g. vendor, employee, contractor.

string

required

Email address for the counterparty.

object

required

Address of the individual.

Show address fields

string

required

Street address line 1. 1–255 characters.

string

Street address line 2. Max 255 characters.

string

required

City. 1–100 characters.

string

State or province. Max 100 characters.

string

Postal or ZIP code. Max 20 characters.

string

required

ISO 3166-1 alpha-2 country code. e.g. US, GB, CA.

array

Identity documents for the individual.

Show identification item fields

string

required

Document type. One of P (passport), D (driving licence), N (national ID).

string

required

Document number.

string

required

ISO 3166-1 alpha-2 country code of the issuing authority.

object

Phone number for the individual.

Show phone fields

string

required

Phone number including country code. e.g. +15125550142.

string

required

Phone type. One of mobile, work, home, other.

string

required

ISO 3166-1 alpha-2 country code for the phone number.

Show Business profile fields

string

required

Registered legal name of the business. 1–255 characters.

string

Trading name or DBA, if different from the legal name. Max 255 characters.

string

required

The relationship of this business counterparty to the entity. e.g. supplier, partner, customer.

string

required

Business contact email address.

object

required

Registered address of the business. Same structure as the individual address object.

array

Business identification documents.

Show identification item fields

string

required

Always L for business identification number.

string

required

Business registration or tax identification number.

string

required

ISO 3166-1 alpha-2 country code of the issuing authority.

object

Business phone number. Same structure as the individual phone object.

The counterparty object

string

Unique identifier for the counterparty. ULID format.

string

The ULID of the entity this counterparty belongs to.

string

The counterparty type. Either individual or business.

string

Human-readable label for the counterparty.

string

Current status of the counterparty. Either active or inactive. Inactive counterparties cannot be used in transfers.

object

Profile details for the counterparty. Shape depends on type.

Show Individual profile fields

string

First name of the individual.

string

Last name of the individual.

string

Relationship of the counterparty to the entity.

string

Email address.

object

Address of the individual, including line1, city, and country.

array

Identity documents. Each item has type, number, and issuing_country.

object

Phone number details, including number, type, and country.

Show Business profile fields

string

Registered legal name of the business.

string

Trading name or DBA, if different from legal name.

string

Relationship of the business counterparty to the entity.

string

Business contact email address.

object

Registered address of the business.

array

Business identification documents.

object

Business phone number details.

object

Additional metadata attached to the counterparty.

number

Unix timestamp in milliseconds of when the counterparty was created.

number

Unix timestamp in milliseconds of the last update to the counterparty.

{
  "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.

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

curl -G https://api.nuvion.dev/counterparties \
  -H "Authorization: Bearer $NUVION_API_KEY" \
  -d entity_id=01KBCFY3VB1XT0MC8VMZXME6RS \
  -d status=active \
  -d limit=20

Query parameters

string

required

Filter counterparties by entity. Required when using API key authentication.

string

Filter by counterparty type. One of individual or business.

string

Filter by status. One of active or inactive.

number

Number of results to return. 1–100. Defaults to 20.

string

Cursor from the previous response’s meta.pagination.next_cursor to fetch the next page.

Response

{
  "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.

curl https://api.nuvion.dev/counterparties/01KM37EZ0AYCVDXJ3WDHXPPSZ9 \
  -H "Authorization: Bearer $NUVION_API_KEY"

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

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"
    }
  }'

Request parameters

string

Reassign or confirm the entity scope for this counterparty.

string

Update the display label for this counterparty. Max 255 characters.

object

Any subset of profile fields to update. Fields not included are not changed. Refer to the profile fields in the create section for the full list of accepted fields.

Returns the updated counterparty object.

Deactivate a counterparty

Deactivates a counterparty, setting its status to inactive.

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

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"
  }'

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

Get Started

Core Concepts

Webhooks

Guides

Counterparties

Create a counterparty

Request parameters

The counterparty object

List counterparties

Query parameters

Response

Get a counterparty

Update a counterparty

Request parameters

Deactivate a counterparty

What’s next

Send a Payout

Counterparties API reference

​Create a counterparty

​Request parameters

​The counterparty object

​List counterparties

​Query parameters

​Response

​Get a counterparty

​Update a counterparty

​Request parameters

​Deactivate a counterparty

​What’s next

Send a Payout

Counterparties API reference

Create a counterparty

Request parameters

The counterparty object

List counterparties

Query parameters

Response

Get a counterparty

Update a counterparty

Request parameters

Deactivate a counterparty

What’s next