Counterparties

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

string

Unique counterparty identifier.

entity_id

string

The entity this counterparty belongs to.

type

string

individual or business.

nickname

string

Display label. Defaults to full name for individuals and legal name for businesses.

status

string

active or inactive. Inactive counterparties cannot receive transfers.

profile

object

Identity details. Shape depends on type.

Show Individual profile fields

first_name

string

First name of the individual.

last_name

string

Last name of the individual.

relationship

string

Relationship to the sending entity. Allowed values: vendor, supplier, customer, employee.

string

Email address of the individual.

address

object

Physical address.

Show Address fields

line1

string

Street address line 1. Required.

line2

string

Street address line 2. Optional.

city

string

City. Required.

state_or_province

string

State or province. Optional.

postal_code

string

Postal or ZIP code. Optional.

country

string

ISO alpha-2 country code. Required.

identification

array

Government-issued identification documents.

Show Identification fields

type

string

Document type. P = passport, D = driving licence, N = national ID.

number

string

Document number.

issuing_country

string

ISO alpha-2 country code of the issuing authority.

phone

object

Phone contact details.

Show Phone fields

number

string

Phone number in E.164 format.

type

string

mobile, work, home, or other.

country

string

ISO alpha-2 country code.

Show Business profile fields

legal_name

string

Registered legal name of the business.

trading_name

string

Trading or DBA name, if different from the legal name. Optional.

relationship

string

Relationship to the sending entity. Allowed values: vendor, supplier, customer, employee.

string

Business contact email.

registered_address

object

Registered business address. Same shape as individual address.

identification

array

Business registration documents.

Show Identification fields

type

string

L = business registration number.

number

string

Registration number.

issuing_country

string

ISO alpha-2 country code of the registering authority.

phone

object

Phone contact details. Same shape as individual phone.

Create a counterparty

POST /counterparties Creates a counterparty of type individual or business. Attach payment details separately after creation.

Request parameters

type

string

required

individual or business.

entity_id

string

required

The entity this counterparty belongs to.

nickname

string

Display label. Defaults to first name + last name for individuals or legal name for businesses.

profile

object

required

Identity details. Required fields differ by type.

Show Individual profile

first_name

string

required

First name.

last_name

string

required

Last name.

relationship

string

required

Relationship to the sending entity. One of: vendor, supplier, customer, employee.

string

required

Email address.

address

object

required

Physical address.

Show Address fields

line1

string

required

Street address line 1.

line2

string

Street address line 2.

city

string

required

City.

state_or_province

string

State or province.

postal_code

string

Postal or ZIP code.

country

string

required

ISO alpha-2 country code (e.g. US, GB).

identification

array

Government-issued identification documents.

Show Identification fields

type

string

required

Document type. P = passport, D = driving licence, N = national ID.

number

string

required

Document number.

issuing_country

string

required

ISO alpha-2 country code of the issuing authority.

phone

object

Phone contact details.

Show Phone fields

number

string

required

Phone number in E.164 format.

type

string

required

mobile, work, home, or other.

country

string

required

ISO alpha-2 country code.

Show Business profile

legal_name

string

required

Registered legal name of the business.

trading_name

string

Trading or DBA name, if different from the legal name.

relationship

string

required

Relationship to the sending entity. One of: vendor, supplier, customer, employee.

string

required

Business contact email.

registered_address

object

required

Registered business address. Same shape as individual address.

identification

array

Business registration documents.

Show Identification fields

type

string

required

L = business registration number.

number

string

required

Registration number.

issuing_country

string

required

ISO alpha-2 country code of the registering authority.

phone

object

Phone contact details. Same shape as individual phone.

Request

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

Response

Returns the created 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

entity_id

string

Filter by entity. Required when authenticating with an API key.

type

string

Filter by counterparty type. individual or business.

status

string

Filter by status. active or inactive.

limit

integer

Number of results to return. Between 1 and 100. Defaults to 20.

cursor

string

Pagination cursor returned in the previous response’s meta.pagination.next_cursor.

Request

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

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": 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

counterparty_id

string

required

The counterparty ID. 26-character ULID.

Query parameters

entity_id

string

Required when authenticating with an API key.

Request

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

Response

Returns 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

counterparty_id

string

required

The counterparty ID. 26-character ULID.

Request parameters

entity_id

string

Required when authenticating with an API key.

nickname

string

Updated display label.

profile

object

Any subset of profile fields for the counterparty’s type. Only provided fields are updated.

Request

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.

Deactivate a counterparty

POST /counterparties/{counterparty_id}/deactivate Sets the counterparty’s status to inactive. Deactivated counterparties cannot receive new transfers.

Deactivation cannot be reversed via the API.

Path parameters

counterparty_id

string

required

The counterparty ID. 26-character ULID.

Request parameters

entity_id

string

Required when authenticating with an API key.

Request

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 with status: "inactive".

Errors

Code	Description
`409`	The counterparty is already inactive.

Add payment details

POST /counterparties/{counterparty_id}/payment-details Attach bank account, mobile money, stablecoin, or book transfer routing information to a counterparty. The returned payment detail ID is used when initiating transfers.

Path parameters

counterparty_id

string

required

The counterparty ID. 26-character ULID.

Request parameters

payment_method

string

required

The payment rail. One of: bank-transfer, momo-transfer, stablecoin-transfer, book-transfer.

currency

string

required

ISO 4217 currency code (e.g. USD, GBP, KES). Use USC for USDC and UST for USDT.

account_holder_name

string

required

Full name of the payment recipient, as it appears on the receiving account.

entity_id

string

required

The entity initiating the payout.

country

string

ISO alpha-2 destination country code. Required for bank transfers.

scheme

string

Payment scheme. Required when the currency supports multiple rails. For USD, specify ach or wire. For GBP, fps or chaps.

Request

curl -X POST https://api.nuvion.dev/counterparties/01KM37EZ0AYCVDXJ3WDHXPPSZ9/payment-details \
  -H "Authorization: Bearer $NUVION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "payment_method": "bank-transfer",
    "currency": "GBP",
    "country": "GB",
    "account_holder_name": "Jane Smith",
    "entity_id": "01KBCFY3VB1XT0MC8VMZXME6RS",
    "sort_code": "040004",
    "account_number": "12345678"
  }'

Response

{
  "id": "pd_01KM37FAABC123DEF456GHI789",
  "payment_method": "bank-transfer",
  "currency": "GBP",
  "country": "GB",
  "scheme": "fps",
  "account_holder_name": "Jane Smith",
  "sort_code": "040004",
  "account_number": "12345678",
  "counterparty_id": "01KM37EZ0AYCVDXJ3WDHXPPSZ9",
  "entity_id": "01KBCFY3VB1XT0MC8VMZXME6RS"
}

See Send a Payout for the complete list of rail-specific required fields across all 24 corridors.

API Reference

​The Counterparty object

​Create a counterparty

​Request parameters

​Request

​Response

​Errors

​List counterparties

​Query parameters

​Request

​Response

​Get a counterparty

​Path parameters

​Query parameters

​Request

​Response

​Update a counterparty

​Path parameters

​Request parameters

​Request

​Response

​Deactivate a counterparty

​Path parameters

​Request parameters

​Request

​Response

​Errors

​Add payment details

​Path parameters

​Request parameters

​Request

​Response

The Counterparty object

Create a counterparty

Request parameters

Request

Response

Errors

List counterparties

Query parameters

Request

Response

Get a counterparty

Path parameters

Query parameters

Request

Response

Update a counterparty

Path parameters

Request parameters

Request

Response

Deactivate a counterparty

Path parameters

Request parameters

Request

Response

Errors

Add payment details

Path parameters

Request parameters

Request

Response