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": "TX", "postal_code": "78701", "country": "US" }, "phone": { "number": "+15125550142", "type": "mobile", "country": "US" }, "identification": [ { "type": "P", "number": "P123456789", "issuing_country": "US" } ] } }'
Request parameters The counterparty type. One of individual or business.
The ULID of the entity this counterparty belongs to.
A human-readable label for the counterparty. Defaults to first_name + last_name for individuals, or legal_name for businesses. Max 255 characters.
Profile fields differ based on type. Show Individual profile fields
First name of the individual. 1–100 characters.
Last name of the individual. 1–100 characters.
The relationship of this counterparty to the entity. e.g. vendor, employee, contractor.
Email address for the counterparty.
Address of the individual. Street address line 1. 1–255 characters.
Street address line 2. Max 255 characters.
State or province. Max 100 characters.
Postal or ZIP code. Max 20 characters.
ISO 3166-1 alpha-2 country code. e.g. US, GB, CA.
Identity documents for the individual. Show identification item fields
Document type. One of P (passport), D (driving licence), N (national ID).
ISO 3166-1 alpha-2 country code of the issuing authority.
Phone number for the individual. Phone number including country code. e.g. +15125550142.
Phone type. One of mobile, work, home, other.
ISO 3166-1 alpha-2 country code for the phone number.
Show Business profile fields
Registered legal name of the business. 1–255 characters.
Trading name or DBA, if different from the legal name. Max 255 characters.
The relationship of this business counterparty to the entity. e.g. supplier, partner, customer.
Business contact email address.
Registered address of the business. Same structure as the individual address object.
Business identification documents. Show identification item fields
Always L for business identification number.
Business registration or tax identification number.
ISO 3166-1 alpha-2 country code of the issuing authority.
Business phone number. Same structure as the individual phone object.
The counterparty object Unique identifier for the counterparty. ULID format.
The ULID of the entity this counterparty belongs to.
The counterparty type. Either individual or business.
Human-readable label for the counterparty.
Current status of the counterparty. Either active or inactive. Inactive counterparties cannot be used in transfers.
Profile details for the counterparty. Shape depends on type. Show Individual profile fields
First name of the individual.
Last name of the individual.
Relationship of the counterparty to the entity.
Address of the individual, including line1, city, and country.
Identity documents. Each item has type, number, and issuing_country.
Phone number details, including number, type, and country.
Show Business profile fields
Registered legal name of the business.
Trading name or DBA, if different from legal name.
Relationship of the business counterparty to the entity.
Business contact email address.
Registered address of the business.
Business identification documents.
Business phone number details.
Additional metadata attached to the counterparty.
Unix timestamp in milliseconds of when the counterparty was created.
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" : "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 Filter counterparties by entity. Required when using API key authentication.
Filter by counterparty type. One of individual or business.
Filter by status. One of active or inactive.
Number of results to return. 1–100. Defaults to 20.
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" : "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 Reassign or confirm the entity scope for this counterparty.
Update the display label for this counterparty. Max 255 characters.
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.
What’s next
Send a Payout Initiate a transfer to a counterparty using their saved payment details.
Counterparties API reference Full endpoint documentation for creating and managing counterparties.
