> ## Documentation Index
> Fetch the complete documentation index at: https://docs.venlyfinance.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Account verification

> Why a new account can't move money yet, and how it becomes verified.

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](/api-reference/Finance-API/accounts/get-account-details)) 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](/api-reference/Finance-API/parties/get-party-details). 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](/api-reference/Finance-API/accounts/get-account-details) 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](/api-reference/Finance-API/wallets/list-wallets-for-an-account) 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](/guides/finance/permits-and-allowances) 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](/guides/finance/wallets).

## What's blocked until `VERIFIED`

These calls fail while an account is `VERIFICATION_PENDING`:

* [Create a crypto transfer](/api-reference/Finance-API/transfers/create-crypto-transfer) and [Create a fiat transfer](/api-reference/Finance-API/transfers/create-fiat-transfer)
* [Create a payment request](/api-reference/Finance-API/payment-requests/create-payment-request-for-account)
* [Create a pay-in session](/api-reference/Finance-API/fiat-to-crypto-payment-sessions/create-a-fiat-to-crypto-payment-session)
* [Create a virtual bank account](/api-reference/Finance-API/virtual-bank-accounts/create-a-virtual-bank-account)

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`:

```json theme={null}
{
  "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`:

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

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

```json theme={null}
{
  "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](/api-reference/Finance-API/transfers/create-crypto-transfer) 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](/guides/finance/permits-and-allowances)

<Note>
  Build the pending state into your flow: create the account, then wait for your Venly contact to verify it (poll [Get an account](/api-reference/Finance-API/accounts/get-account-details) until `kycStatus` is `VERIFIED`) before attempting transfers, payments, pay-ins, or virtual bank accounts.
</Note>

## Next steps

<CardGroup cols={2}>
  <Card title="Approve transfers (self-custody)" icon="key" href="/guides/finance/permits-and-allowances">
    Activate a self-custody wallet so Venly can move its funds.
  </Card>

  <Card title="Integration walkthrough" icon="route" href="/guides/finance/integration-walkthrough">
    See verification within the full end-to-end flow.
  </Card>
</CardGroup>