> ## 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.

# Onboarding lifecycle

> From a brand-new party to an account that can move money — the states, the gates, and who clears them.

Nothing moves money until the right things are verified. This page is the map: what gets created, what gets verified, and which gate blocks what.

```mermaid theme={null}
flowchart TD
    T["Company tenant provisioned<br/><i>Venly, once per company</i>"] --> P["Create party<br/><i>unverified</i>"]
    P --> V{"Verification route"}
    V -->|"Hosted link"| H["End-user completes<br/>Venly-hosted flow"]
    V -->|"Sumsub token"| S["Forward a verification<br/>you already ran"]
    V -->|"Tenant-managed<br/><i>flag required</i>"| N["You verify;<br/>declare NOT_REQUIRED"]
    H --> W["Verdict applied<br/><i>kycStatus / kybStatus</i>"]
    S --> W
    W --> A["Account VERIFIED"]
    N --> A
    A --> C{"Partner terms<br/>outstanding?"}
    C -->|"Yes"| CP["End customer accepts<br/>on hosted consent page"]
    C -->|"No"| M
    CP --> M["Wallet AML APPROVED<br/>+ permit if self-custody"]
    M --> R["Can move money"]
```

## The four things that get cleared

People confuse these constantly, so it's worth separating them up front. They are **not** the same gate.

| # | What                          | Field                      | Who clears it                                                                               |
| - | ----------------------------- | -------------------------- | ------------------------------------------------------------------------------------------- |
| 1 | **Your company** (the tenant) | —                          | Venly, once, before you can call verification endpoints at all                              |
| 2 | **The party** (your end-user) | `kycStatus` / `kybStatus`  | Venly, per party                                                                            |
| 3 | **Partner terms**             | consent state on the party | **Your end customer**, on a [hosted page](/guides/finance/onboarding/partner-terms-consent) |
| 4 | **The wallet**                | `amlStatus` (+ permit)     | Screening, per wallet                                                                       |

All four must be clear. A `VERIFIED` party with a `FLAGGED` wallet still cannot move money — see [Wallet readiness](/guides/finance/kyc-verification#wallet-readiness-aml-and-permits-for-self-custody).

<Note>
  Your company tenant is provisioned by Venly, not through the API. If it isn't, every verification call fails with `verification-not-provisioned` — and no amount of retrying will fix it. See [Troubleshooting](/guides/finance/onboarding/troubleshooting).
</Note>

## Party vs. account

A party's `status` is `ACTIVE` the moment you create it. **That is not verification.** It means the record is usable, not that the person behind it has been identified.

| Object  | Field                     | Starts at                          | Meaning                                          |
| ------- | ------------------------- | ---------------------------------- | ------------------------------------------------ |
| Party   | `status`                  | `ACTIVE`                           | The record is live. Says nothing about identity. |
| Party   | `kycStatus` / `kybStatus` | `VERIFICATION_PENDING` / `PENDING` | Identity verification state.                     |
| Account | `kycStatus`               | `VERIFICATION_PENDING`             | **This is the gate on money movement.**          |

The account's `kycStatus` is what every money-movement endpoint checks. It follows from its account-holder party's verification.

## Pick a route

**Two routes carry a production integration**, and which you can use is mostly decided for you:

<CardGroup cols={2}>
  <Card title="Hosted verification link" icon="link" href="/guides/finance/onboarding/hosted-verification">
    Venly hosts the flow; you hand over a URL. **Works for individuals and organisations.** The default.
  </Card>

  <Card title="Sumsub token sharing" icon="forward" href="/guides/finance/onboarding/sumsub-token-sharing">
    Forward a verification you already ran in your own Sumsub account. **Individuals on self-custody only.**
  </Card>
</CardGroup>

| If you…                                                          | Use                                                                                                         |
| ---------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| Have no existing KYC provider                                    | [Hosted verification link](/guides/finance/onboarding/hosted-verification)                                  |
| Are verifying a business                                         | [Hosted verification link](/guides/finance/onboarding/hosted-verification) — KYB has no token-sharing route |
| Already verified this individual in Sumsub, and run self-custody | [Sumsub token sharing](/guides/finance/onboarding/sumsub-token-sharing)                                     |
| Run your own full compliance stack                               | One of the two above — see the note below                                                                   |

<Note>
  There is a third path, [tenant-managed KYC](/guides/finance/kyc-verification#tenant-managed-kyc), where
  you declare `kycStatus: NOT_REQUIRED` on the account and Venly doesn't gate on its own verification.

  It is **not something you can switch on yourself**: a Venly admin has to enable the flag on your company
  tenant, and without it the call fails with `kyc-not-required-not-allowed`. In practice it's granted for
  testing rather than production use, so **plan your production integration around a hosted link or Sumsub
  token sharing** and treat tenant-managed KYC as a way to exercise money movement without real
  verifications.
</Note>

## Verdicts are asynchronous

No verification route returns a verdict inline. In every case you create or forward something, get an acknowledgement, and the outcome lands later.

That shapes your integration: **build the pending state in from the start.** Don't write code that assumes a party is verified immediately after you mint a link.

<Steps>
  <Step title="Trigger verification">
    Mint a link, or forward a token at account creation.
  </Step>

  <Step title="Wait">
    [Register a webhook](/guides/finance/webhooks) so the verdict is pushed to you. Polling
    [Get a party](/api-reference/Finance-API/parties/get-party-details) works, but verdicts are
    human-paced — polling for hours is wasteful.
  </Step>

  <Step title="Read the outcome">
    `kycStatus` (individuals) or `kybStatus` (organisations) on the party; `kycStatus` on the account
    for the money-movement gate.
  </Step>
</Steps>

## What you can do while unverified

Plenty. Verification blocks money movement, not setup:

| Available before verification                                                                                                                            | Blocked until verified                                                                                                |
| -------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| Create parties and accounts                                                                                                                              | Crypto and fiat [transfers](/guides/finance/transfers)                                                                |
| Add and remove party roles                                                                                                                               | [Transfers](/guides/finance/transfers)                                                                                |
| Read wallets, balances, permits, allowances                                                                                                              | [Pay-in sessions](/api-reference/Finance-API/fiat-to-crypto-payment-sessions/create-a-fiat-to-crypto-payment-session) |
| Sign and submit the self-custody [permit](/guides/finance/permits-and-allowances)                                                                        | [Virtual bank accounts](/guides/finance/virtual-bank-accounts)                                                        |
| Register [payout bank accounts](/api-reference/Finance-API/payout-bank-accounts/register-a-payout-bank-account) and [webhooks](/guides/finance/webhooks) | [Pay-outs](/guides/finance/payouts)                                                                                   |

Front-load that left column while verification is in flight.

## Next steps

<CardGroup cols={2}>
  <Card title="Roles & entities" icon="sitemap" href="/guides/finance/onboarding/roles-and-entities">
    Company, party, account, and role — which object holds what.
  </Card>

  <Card title="Individual KYC" icon="user" href="/guides/finance/onboarding/individual-kyc">
    Verifying a natural person.
  </Card>

  <Card title="Business KYB" icon="building" href="/guides/finance/onboarding/business-kyb">
    Verifying a company or business.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/guides/finance/onboarding/troubleshooting">
    Every verification error code and what to do about it.
  </Card>
</CardGroup>