Account verification

Every account starts unverified and must be verified before it can move money. This is the most common reason an otherwise-correct request is rejected, so it’s worth understanding early.

The states

An account’s kycStatus (returned by Get an account) is one of:

`kycStatus`	Meaning
`VERIFICATION_PENDING`	New account. Can be set up, but can’t move money yet.
`VERIFIED`	Approved. All operations are available.
`REJECTED`	Verification was declined.

Individuals and organisations (KYC & KYB)

The account’s kycStatus above is what gates money movement. The underlying party is verified too, on a field that depends on its type:

Party type	Field	States
`INDIVIDUAL`	`kycStatus`	`VERIFICATION_PENDING → VERIFIED` (or `REJECTED`)
`ORGANISATION`	`kybStatus`	`PENDING → VERIFIED` (or `DENIED`)

KYB (Know Your Business) is the organisation equivalent of KYC — it verifies the company itself (and, typically, its representatives). Read kybStatus from Get a party. Like KYC, it’s reviewed by a Venly admin and runs asynchronously after you create the organisation party.

How an account gets verified

Verification is reviewed and approved by a Venly admin — it does not happen through the API, and there’s no endpoint to trigger it. After you create an account, your Venly contact reviews it; once approved, the account’s kycStatus becomes VERIFIED. Check the current status at any time with Get an account and read the kycStatus field.

Wallet readiness (AML, and permits for self-custody)

A VERIFIED kycStatus clears the account, but funds move through the account’s wallet, which has its own gate. Each wallet returned by list wallets carries an amlStatus (PENDING → APPROVED). An account is ready to move money when:

Custody	Ready when
Venly-managed	`kycStatus` is `VERIFIED` and the wallet’s `amlStatus` is `APPROVED` (both happen during onboarding — no further action).
Self-custody	the above plus a `CONFIRMED` permit on the account wallet — the one-time signature that lets Venly move its funds.

The wallet has no status field, so use amlStatus (Venly-managed) and permit status (self-custody) as your readiness signals. See Wallets & balances.

What’s blocked until `VERIFIED`

These calls fail while an account is VERIFICATION_PENDING:

Each returns an error that means “this account isn’t verified yet” — but the error code and HTTP status depend on the operation, so handle any of them as not-verified rather than matching a single code:

Virtual bank account → 400 with code kyc-not-verified:

{
  "success": false,
  "errors": [
    { "code": "kyc-not-verified", "message": "Account KYC status must be VERIFIED to create a virtual bank account. Current status: VERIFICATION_PENDING" }
  ]
}

Pay-in session → 422 with code kyc-required:

{
  "success": false,
  "errors": [
    { "code": "kyc-required", "message": "Account {accountId} KYC status is not verified" }
  ]
}

Payment request → 400 with code account-not-active:

{
  "success": false,
  "errors": [
    { "code": "account-not-active", "message": "Account KYC status must be VERIFIED to authorize payments. Current status: VERIFICATION_PENDING" }
  ]
}

Transfers are gated the same way; check the transfer endpoints for the exact status code.

What you can do before verification

Plenty of setup doesn’t require a verified account:

Create parties and accounts
Add and remove party roles
Read wallets, balances, permits, and allowances
For self-custody, sign and submit the token permit — see Approving transfers without gas

Build the pending state into your flow: create the account, then wait for your Venly contact to verify it (poll Get an account until kycStatus is VERIFIED) before attempting transfers, payments, pay-ins, or virtual bank accounts.

Overview

Core Concepts

Parties

Accounts

Virtual Bank Accounts

Wallets

Transfers

Payment Requests

Fiat to Crypto Payment Sessions

Permits

Allowances

Reference

The states

Individuals and organisations (KYC & KYB)

How an account gets verified

Wallet readiness (AML, and permits for self-custody)

What’s blocked until `VERIFIED`

What you can do before verification

Next steps

Approve transfers (self-custody)

Integration walkthrough

​The states

​Individuals and organisations (KYC & KYB)

​How an account gets verified

​Wallet readiness (AML, and permits for self-custody)

​What’s blocked until VERIFIED

​What you can do before verification

​Next steps

Approve transfers (self-custody)

Integration walkthrough

The states

Individuals and organisations (KYC & KYB)

How an account gets verified

Wallet readiness (AML, and permits for self-custody)

What’s blocked until `VERIFIED`

What you can do before verification

Next steps