Skip to main content
POST
Create a new account
Requires scope: manage:accounts — see Required scopes. Creates an account and its wallet. Link an existing party with partyId, or create one inline with the party object. Self-custody accounts also supply the wallet address — see Venly-managed vs self-custody. A new account inherits its holder’s verification: link a partyId that is already VERIFIED and the account is created VERIFIED, ready to move money; a holder with no outcome yet gives VERIFICATION_PENDING, which can’t move money until it is verified.

Errors

The codes this endpoint can return, in addition to the standard errors. Branch on code, never the message.

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

Create a new account. You can either:

  • Reference an existing party by providing partyId
  • Create a new party inline by providing the party object

SELF_CUSTODY companies must also supply the wallet address.

externalId
string
required

Unique external reference for this account

Minimum string length: 1
chain
enum<string>
required

Supported blockchain network. Availability per chain depends on your company's configured supportedChains — see Supported chains and assets.

Available options:
AVALANCHE,
BASE,
ETHEREUM,
POLYGON,
SOLANA
name
string

Display name for the account

Required string length: 1 - 255
address
string

Wallet address. Required for SELF_CUSTODY companies

partyId
string<uuid>

ID of an existing party to associate as account holder

party
object
Example:
cardProviderReference
object
kycStatus
enum<string>

Optional initial KYC status. Only NOT_REQUIRED is settable — it declares that you verify end-users within your own compliance stack, so Venly does not gate money movement on its own verification. It is never overridden by the holder's own outcome.

Omit the field and the server derives the status from the party named by partyId: an already-verified holder yields a VERIFIED account, a rejected one a REJECTED account, and anything else VERIFICATION_PENDING.

This requires a Venly admin to enable the tenant-managed KYC flag on your company tenant. You cannot switch it on yourself, and until it is enabled the call fails with kyc-not-required-not-allowed. In practice the flag is granted for testing rather than production use — production integrations verify via a hosted verification link or Sumsub token sharing.

Supplying VERIFIED or REJECTED is rejected with kyc-status-not-settable. Omit the field for the normal flow.

Available options:
VERIFICATION_PENDING,
VERIFIED,
NOT_REQUIRED,
REJECTED

Response

Account created

success
boolean

Indicates whether the request was successful

result
object

The account as returned by POST /accounts: the Account fields plus, only when a forwarded sumsubToken still needs the customer to act, the verification block.