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.

string

The entity this counterparty belongs to.

string

individual or business.

string

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

string

active or inactive. Inactive counterparties cannot receive transfers.

object

Identity details. Shape depends on type.

Show Individual profile fields

string

First name of the individual.

string

Last name of the individual.

string

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

string

Email address of the individual.

object

Physical address.

Show Address fields

string

Street address line 1. Required.

string

Street address line 2. Optional.

string

City. Required.

string

State or province. Optional.

string

Postal or ZIP code. Optional.

string

ISO alpha-2 country code. Required.

array

Government-issued identification documents.

Show Identification fields

string

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

string

Document number.

string

ISO alpha-2 country code of the issuing authority.

object

Phone contact details.

Show Phone fields

string

Phone number in E.164 format.

string

mobile, work, home, or other.

string

ISO alpha-2 country code.

Show Business profile fields

string

Registered legal name of the business.

string

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

string

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

string

Business contact email.

object

Registered business address. Same shape as individual address.

array

Business registration documents.

Show Identification fields

string

L = business registration number.

string

Registration number.

string

ISO alpha-2 country code of the registering authority.

object

Phone contact details. Same shape as individual phone.

object

Arbitrary key-value metadata.

number

0 if the counterparty is active. Non-zero if the counterparty has been deleted.

number

Unix timestamp (milliseconds) when the counterparty was created.

number

Unix timestamp (milliseconds) when the counterparty was last updated.

{
  "status": "success",
  "message": "Counterparty created successfully",
  "data": {
    "id": "01HXYZ4001ABCDEFGHJKMNPQRS",
    "entity_id": "01HXYZ1234ABCDEFGHJKMNPQRS",
    "type": "individual",
    "nickname": "Ada Whitfield",
    "status": "active",
    "profile": {
      "first_name": "Ada",
      "last_name": "Whitfield",
      "relationship": "vendor",
      "address": {
        "line1": "1 Payee Road",
        "city": "Austin",
        "state_or_province": "TX",
        "postal_code": "78701",
        "country": "US"
      },
      "email": "ada.whitfield@example.com"
    },
    "created": 1787286621446,
    "updated": 1787286621446,
    "deleted": 0
  }
}

Create a counterparty

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

Request parameters

string

required

individual or business.

string

The entity this counterparty belongs to. Defaults to the authenticating entity when omitted. Required when acting on a child entity. See Managing child entities for details.

string

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

object

required

Identity details. Required fields differ by type.

Show Individual profile

string

required

First name.

string

required

Last name.

string

required

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

string

required

Email address.

object

required

Physical address.

Show Address fields

string

required

Street address line 1.

string

Street address line 2.

string

required

City.

string

State or province.

string

Postal or ZIP code.

string

required

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

array

Government-issued identification documents.

Show Identification fields

string

required

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

string

required

Document number.

string

required

ISO alpha-2 country code of the issuing authority.

object

Phone contact details.

Show Phone fields

string

required

Phone number in E.164 format.

string

required

mobile, work, home, or other.

string

required

ISO alpha-2 country code.

Show Business profile

string

required

Registered legal name of the business.

string

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

string

required

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

string

required

Business contact email.

object

required

Registered business address. Same shape as individual address.

array

Business registration documents.

Show Identification fields

string

required

L = business registration number.

string

required

Registration number.

string

required

ISO alpha-2 country code of the registering authority.

object

Phone contact details. Same shape as individual phone.

object

Arbitrary key-value metadata. Keys and values must be strings.

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": "01HXYZ1234ABCDEFGHJKMNPQRS",
    "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"
      }
    }
  }'

curl -X POST https://api.nuvion.dev/counterparties \
  -H "Authorization: Bearer $NUVION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "business",
    "entity_id": "01HXYZ1234ABCDEFGHJKMNPQRS",
    "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"
      },
      "identification": [
        {
          "type": "L",
          "number": "EIN-47-9876543",
          "issuing_country": "US"
        }
      ],
      "phone": {
        "number": "+12125550199",
        "type": "work",
        "country": "US"
      }
    }
  }'

Response

Returns the created Counterparty object.

{
  "status": "success",
  "message": "Counterparty created successfully",
  "data": {
    "id": "01HXYZ4002ABCDEFGHJKMNPQRS",
    "entity_id": "01HXYZ1234ABCDEFGHJKMNPQRS",
    "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"
      }
    },
    "created": 1787287000000,
    "updated": 1787287000000,
    "deleted": 0
  }
}

{
  "status": "success",
  "message": "Counterparty created successfully",
  "data": {
    "id": "01HXYZ4006ABCDEFGHJKMNPQRS",
    "entity_id": "01HXYZ1234ABCDEFGHJKMNPQRS",
    "type": "business",
    "nickname": "Acme Corp Ltd",
    "status": "active",
    "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"
      },
      "identification": [
        {
          "type": "L",
          "number": "EIN-47-9876543",
          "issuing_country": "US"
        }
      ],
      "phone": {
        "number": "+12125550199",
        "type": "work",
        "country": "US"
      }
    },
    "created": 1787288000000,
    "updated": 1787288000000,
    "deleted": 0
  }
}

Errors

Code	Description
`422`	Validation error: a required field is missing or a field value is invalid.
`409`	The specified `entity_id` was not found.

List counterparties

GET /counterparties Returns a paginated list of counterparties.

Query parameters

string

Filter by entity. Defaults to the authenticating entity when omitted. Required when acting on a child entity. See Managing child entities for details.

string

Filter by counterparty type. individual or business.

string

Filter by status. active or inactive.

integer

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

string

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

Request

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

Response

{
  "status": "success",
  "message": "Counterparties retrieved successfully",
  "data": {
    "data": [
      {
        "id": "01HXYZ4001ABCDEFGHJKMNPQRS",
        "entity_id": "01HXYZ1234ABCDEFGHJKMNPQRS",
        "type": "individual",
        "nickname": "Ada Whitfield",
        "status": "active",
        "profile": {
          "first_name": "Ada",
          "last_name": "Whitfield",
          "relationship": "vendor",
          "address": {
            "line1": "1 Payee Road",
            "city": "Austin",
            "state_or_province": "TX",
            "postal_code": "78701",
            "country": "US"
          },
          "email": "ada.whitfield@example.com"
        },
        "created": 1787286621446,
        "updated": 1787286621446,
        "deleted": 0
      }
    ],
    "meta": {
      "pagination": {
        "order": "desc",
        "has_next": true,
        "limit": 1,
        "has_previous": false,
        "next_cursor": "01HXYZ4001ABCDEFGHJKMNPQRS",
        "previous_cursor": null
      }
    }
  }
}

Get a counterparty

GET /counterparties/{counterparty_id} Retrieves a single counterparty by ID.

Path parameters

string

required

The counterparty ID. 26-character ULID.

Query parameters

string

Defaults to the authenticating entity when omitted. Required when acting on a child entity. See Managing child entities for details.

Request

curl "https://api.nuvion.dev/counterparties/01HXYZ4002ABCDEFGHJKMNPQRS" \
  -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

string

required

The counterparty ID. 26-character ULID.

Request parameters

string

Defaults to the authenticating entity when omitted. Required when acting on a child entity. See Managing child entities for details.

string

Updated display label.

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/01HXYZ4002ABCDEFGHJKMNPQRS \
  -H "Authorization: Bearer $NUVION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "entity_id": "01HXYZ1234ABCDEFGHJKMNPQRS",
    "profile": {
      "email": "jane.updated@example.com"
    }
  }'

Response

Returns the updated Counterparty object.

List counterparty payment details

GET /counterparties/{counterparty_id}/payment-details Returns the payment details attached to a counterparty.

Path parameters

string

required

The counterparty ID. 26-character ULID.

Query parameters

string

Defaults to the authenticating entity when omitted. Required when acting on a child entity. See Managing child entities for details.

Request

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

Response

Returns a paginated list of payment detail objects.

Response

{
  "status": "success",
  "message": "Payment details retrieved successfully",
  "data": {
    "data": [
      {
        "id": "01HXYZ4004ABCDEFGHJKMNPQRS",
        "payment_method": "bank-transfer",
        "currency": "CAD",
        "account_holder_name": "Janet Mercer",
        "counterparty_id": "01HXYZ4003ABCDEFGHJKMNPQRS",
        "entity_id": "01HXYZ1234ABCDEFGHJKMNPQRS",
        "scheme": "eft",
        "account_number": "1022573",
        "country": "CA",
        "bank_institution_number": "006",
        "bank_name": "National Bank of Canada (Banque Nationale du Canada)",
        "transit_number": "09591"
      },
      {
        "id": "01HXYZ4005ABCDEFGHJKMNPQRS",
        "payment_method": "stablecoin-transfer",
        "currency": "USC",
        "account_holder_name": "Janet Mercer",
        "counterparty_id": "01HXYZ4003ABCDEFGHJKMNPQRS",
        "entity_id": "01HXYZ1234ABCDEFGHJKMNPQRS",
        "scheme": "stablecoin",
        "wallet_address": "0x444444444444444444444444444444444444DDDD",
        "blockchain_network": "ETH_MAINNET"
      }
    ],
    "meta": {
      "pagination": {
        "order": "asc",
        "has_next": false,
        "limit": 20,
        "has_previous": false,
        "next_cursor": null,
        "previous_cursor": null
      }
    }
  }
}

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

string

required

The counterparty ID. 26-character ULID.

Request parameters

string

Defaults to the authenticating entity when omitted. Required when acting on a child entity. See Managing child entities for details.

Request

curl -X POST "https://api.nuvion.dev/counterparties/01HXYZ4002ABCDEFGHJKMNPQRS/deactivate" \
  -H "Authorization: Bearer $NUVION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "entity_id": "01HXYZ1234ABCDEFGHJKMNPQRS" }'

Response

Returns the updated Counterparty object with status: "inactive".

Errors

Code	Description
`409`	The counterparty is already inactive.

​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

​List counterparty payment details

​Path parameters

​Query parameters

​Request

​Response

​Deactivate a counterparty

​Path parameters

​Request parameters

​Request

​Response

​Errors

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

List counterparty payment details

Path parameters

Query parameters

Request

Response

Deactivate a counterparty

Path parameters

Request parameters

Request

Response

Errors