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.
`NOT_REQUIRED`	You verify end-users yourself; Venly does not gate on its own verification. Requires a flag a Venly admin enables on your tenant — see tenant-managed KYC below.

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 runs asynchronously after you create the organisation party.

How a party gets verified

You drive verification through the API. There are two routes:

Hosted verification link

POST /parties/{partyId}/verification mints a link you hand to the end-user. Works for individuals (KYC) and organisations (KYB).

Forward a Sumsub token

Already verified the user yourself? Pass party.sumsubToken at account creation. Individuals on self-custody only.

The verdict arrives asynchronously and flips the party’s kycStatus/kybStatus. See the onboarding lifecycle for the full picture, Individual KYC and Business KYB for each party type, and Troubleshooting for error codes and tracking linkage. Check the current status at any time with Get an account and read the kycStatus field.

Tenant-managed KYC

Passing kycStatus: NOT_REQUIRED when creating an account declares that you verify end-users within your own compliance stack, so Venly does not gate money movement on its own verification. It lets you reach transfers and pay-outs without completing a verification flow per party.

You cannot enable this yourself. A Venly admin must turn the tenant-managed KYC flag on for your company tenant. Until they do, supplying NOT_REQUIRED fails with kyc-not-required-not-allowed — it is not a request you can retry your way past.In practice the flag is granted for testing, not for production use. Production integrations verify through a hosted verification link or Sumsub token sharing.

Constraints:

NOT_REQUIRED is the only client-settable value. Supplying VERIFIED or REJECTED is rejected with kyc-status-not-settable.
It only works where a Venly admin has enabled the flag on the company tenant. Otherwise: kyc-not-required-not-allowed.
It is settable only at account creation — you can’t move an existing account to NOT_REQUIRED.

Omit kycStatus entirely for the normal flow.

Don’t let this path shape your integration. If your test accounts always use NOT_REQUIRED, you never exercise the pending-verification state — and the first account that has to wait for a real verdict will block on a code path you never ran. Build the pending state regardless.

Verification is not the last step

VERIFIED means we know who the party is. It does not mean our partners will deal with them yet: the end customer must also accept those partners’ terms themselves, on a page we hand them a link to. That acceptance is tracked in its own field on the party — not in kycStatus — and it gates virtual bank accounts and pay-outs. See Partner-terms consent.

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:

`amlStatus`	Meaning
`PENDING`	Screening in progress. Money movement is blocked.
`APPROVED`	Cleared.
`FLAGGED`	Flagged for manual review. Money movement is blocked.
`BLOCKED`	Screening blocked the wallet. Money movement is blocked.

Treat anything other than APPROVED as not-ready — FLAGGED and BLOCKED need Venly intervention, so surface them rather than retrying in a loop. 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:

Create a crypto transfer and Create a fiat transfer
Create a pay-in session
Create a virtual bank account
Request a payout — plus the recipient party needs cleared KYC/KYB before a route can even be created

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" }
  ]
}

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
Mint a verification link and read verification linkage
Add and remove party roles
Read wallets, balances, permits, and allowances
Register payout bank accounts and webhooks
For self-custody, sign and submit the token permit — see Approving transfers without gas

Build the pending state into your flow: create the account, send the party through verification, then wait for the verdict — register a webhook rather than polling, or poll Get an account until kycStatus is VERIFIED — before attempting transfers, payments, pay-ins, pay-outs, or virtual bank accounts.

Next steps

Onboarding lifecycle

The three gates, both verification routes, and what’s blocked when.

Approve transfers (self-custody)

Activate a self-custody wallet so Venly can move its funds.

Integration walkthrough

See verification within the full end-to-end flow.

Webhooks

Get verdicts pushed to you instead of polling.

Overview

Recipes

Onboarding & Verification

Core Concepts

Parties

Accounts

Virtual Bank Accounts

Supported Assets

Wallets

Transfers

Fiat to Crypto Payment Sessions

Payout Bank Accounts

Payout Routes

Payouts

Permits

Allowances

Webhooks

Reference

The states

Individuals and organisations (KYC & KYB)

How a party gets verified

Hosted verification link

Forward a Sumsub token

Tenant-managed KYC

Verification is not the last step

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

What’s blocked until `VERIFIED`

What you can do before verification

Next steps

Onboarding lifecycle

Approve transfers (self-custody)

Integration walkthrough

Webhooks

​The states

​Individuals and organisations (KYC & KYB)

​How a party gets verified

Hosted verification link

Forward a Sumsub token

​Tenant-managed KYC

​Verification is not the last step

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

​What’s blocked until VERIFIED

​What you can do before verification

​Next steps

Onboarding lifecycle

Approve transfers (self-custody)

Integration walkthrough

Webhooks

The states

Individuals and organisations (KYC & KYB)

How a party gets verified

Tenant-managed KYC

Verification is not the last step

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

What’s blocked until `VERIFIED`

What you can do before verification

Next steps