> ## 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` — or `VERIFIED` straight away if the holder already is | **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 — including at creation: an account opened for an already-verified party is created `VERIFIED`, so a customer's second account needs no second 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>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.