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 starts unverified and 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

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.

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