Skip to main content
POST
Create a new party
Requires scope: manage:parties — see Required scopes. Creates a party. Use partyType: INDIVIDUAL with firstName/lastName, or ORGANISATION with name (and optional vatNumber). The returned id is what you pass when opening an account. Identity verification runs asynchronously after creation — track it on kycStatus (individuals) or kybStatus (organisations); see Account verification.

Authorizations

Body

application/json
partyType
enum<string>
required

Type of party

Available options:
INDIVIDUAL,
ORGANISATION
externalId
string

Optional external reference ID

Maximum string length: 255
firstName
string

Required for INDIVIDUAL parties

Maximum string length: 100
lastName
string

Required for INDIVIDUAL parties

Maximum string length: 100
name
string

Organisation name. Required for ORGANISATION parties

Maximum string length: 255
vatNumber
string

VAT number. ORGANISATION parties only

Maximum string length: 50
email
string<email> | null

Contact email for the party. Optional, but supply a real one up front for an individual on a self-custody account.

When an account holder is onboarded to a partner their email is forwarded with the case. If the party has none, a synthetic <case-id>@venlyfinance.com address is used so onboarding still proceeds — and because the partner stores that email write-once, adding a real address later does not replace the synthetic one. There is no way to correct it afterwards.

Maximum string length: 255
address
object

Standardized address format used across all endpoints

sumsubToken
string
write-only

Optional Sumsub share token, forwarding a verification you already completed in your own Sumsub account. Accepted only when creating a party inline via Create an accountPOST /parties rejects it with 400 sumsub-token-not-supported.

Requires partyType: INDIVIDUAL (KYC only), a SELF_CUSTODY company wallet type, and a provisioned verification tenant. Never persisted and never returned. If the forward fails, the entire account-creation transaction is rolled back — retry with a fresh token.

See Sumsub token sharing.

Maximum string length: 4096

Response

Party created

success
boolean

Indicates whether the request was successful

result
object

A party represents an Individual or Organisation that can hold accounts. The partyType field determines which additional fields are present.