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

Headers

x-tenant-id
string<uuid>

Which tenant the request is scoped to, among those your token grants. Omit it when the token grants exactly one tenant; it is required when the token grants more than one. A supplied value must exactly match a tenant the token grants.

Absent when required, blank, malformed, or naming a tenant the token does not grant — each gets the same generic 403 forbidden, which reveals neither whether a tenant exists nor which ones you may use. Send the header once: a repeated header is rejected the same way.

Example:

"3fa85f64-5717-4562-b3fc-2c963f66afa6"

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, kept as your own record. Optional — omitting it never blocks an onboarding. When an account holder is onboarded to a partner, the email travels only as far as Venly's verification case: the partner is given a Venly-controlled address instead, so its operational and pricing mail never reaches the party directly.

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 account — POST /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.