Parties
Create and manage end-user entities. Intents resolve the party from the wallet on file.
A party represents one of your end-users to Nora. It carries identity
data and a single connected Solana wallet via profile.solanaWallet.
Error envelope
All parties endpoints return errors in the parties-family shape:
{ "error": "human-readable message", "code": "optional_machine_code" }error is always present; code may be present for specific failures.
See Error handling for
the full taxonomy.
POST /v2/parties
Create a new party.
Headers
| Header | Required | Notes |
|---|---|---|
X-API-Key | Yes | |
Content-Type | Yes | application/json |
Request body
| Field | Type | Required | Description |
|---|---|---|---|
cpf | string | Yes | 11-digit CPF (person) or 14-digit CNPJ (business), digits only. |
displayName | string | Yes | 2–100 characters. |
partyType | "person" | "business" | No | Default "person". |
countryCode | string | No | ISO 3166-1 alpha-2. Default "BR". |
externalRef | string | No | Your own correlation reference. |
email | string | No | Valid email address. |
phone | string | No |
Response 201
| Field | Type | Required | Description |
|---|---|---|---|
id | string (uuid) | Yes | Nora-assigned party id. |
instanceId | string (uuid) | Yes | The instance this party belongs to. |
partyType | "person" | "business" | Yes | |
countryCode | string | Yes | |
externalRef | string | null | Yes | Echoed if you supplied one; null otherwise. |
status | "pending" | "active" | "suspended" | "blocked" | Yes | |
profile | object | Yes | See below. |
createdAt | string | Yes | ISO 8601 timestamp. |
updatedAt | string | Yes |
profile sub-object:
| Field | Type | Required | Description |
|---|---|---|---|
displayName | string | Yes | |
documentType | string | Yes | e.g. "cpf" or "cnpj". |
documentMasked | string | Yes | Masked rendering, e.g. "***.***.***-01". |
solanaWallet | string | null | Yes | The bound Solana wallet, null until bound. |
Example
curl -X POST https://staging.api.nora.finance/v2/parties \
-H "X-API-Key: $NORA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"cpf": "12345678901",
"displayName": "João da Silva",
"partyType": "person",
"countryCode": "BR",
"email": "joao@example.com",
"externalRef": "user_123"
}'{
"id": "2f1b4a2e-4c9e-4a5b-8c8b-...",
"instanceId": "4e0b9c7a-11d9-4f3c-9a6a-...",
"partyType": "person",
"countryCode": "BR",
"externalRef": "user_123",
"status": "pending",
"profile": {
"displayName": "João da Silva",
"documentType": "cpf",
"documentMasked": "***.***.***-01",
"solanaWallet": null
},
"createdAt": "2026-04-22T12:00:00Z",
"updatedAt": "2026-04-22T12:00:00Z"
}Errors
400 { error, code? }— validation failure (missing required field, bad document format, etc.).409 { error, code? }— conflict (e.g. party already exists for this document).
GET /v2/parties/:id
Fetch one party by id.
Path parameters
| Param | Type | Required |
|---|---|---|
id | string (uuid) | Yes |
Headers
| Header | Required |
|---|---|
X-API-Key | Yes |
Response 200
Same shape as the POST /v2/parties 201 response.
Errors
404 { error, code? }— no party with that id in this org/instance.
PATCH /v2/parties/:id/wallet
Bind the party's Solana wallet, or replace an existing binding. Only one Solana wallet per party.
Path parameters
| Param | Type | Required |
|---|---|---|
id | string (uuid) | Yes |
Headers
| Header | Required | Notes |
|---|---|---|
X-API-Key | Yes | |
Content-Type | Yes | application/json |
Request body
| Field | Type | Required | Description |
|---|---|---|---|
solanaWallet | string | Yes | Solana wallet address to bind. Replaces any previous binding. |
This is the only field. No chainId, no envelope.
Response 200
Returns the full party object — same shape as GET /v2/parties/:id —
with profile.solanaWallet set to the address you just bound.
Errors
400 { error, code? }— body validation (e.g. missingsolanaWallet).404 { error, code? }— no party with that id.