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

# User Onboarding

> A consolidated, audit friendly view of portfolio value, balances, positions, and activity for end users of an institution-operated Levery instance.

Onboarding in Levery is the institution’s **customer admission and account provisioning workflow**. It establishes a
controlled path from an end user’s identity record to a permissioned account that can access regulated markets under
institutional policy. Access is granted only after the platform has strong signals that:

* the user controls the email address they registered with,
* the institution has the minimum required user information on record,
* identity verification (KYC) has been completed, and
* the user controls the wallet account that will be used to access permissioned markets.

This flow is intentionally structured as a sequence of checks. Each step reduces risk, improves auditability, and
creates a clear basis for approval decisions, whether those approvals are automated or completed by a compliance team.

<Callout type="info" title="Who this guide is for">
  This page guides end users of a financial institution that runs its own Levery instance. It also highlights
  configuration points where the institution can strengthen security, improve deliverability, and reduce onboarding
  friction.
</Callout>

***

## What onboarding achieves for the institution

A properly configured onboarding policy allows an institution to:

* enforce identity verification before allowing access to restricted products,
* ensure every wallet account is linked to a verified user record,
* maintain an auditable trail of verification and approval decisions,
* reduce fraud and account takeover risk through one-time codes and wallet ownership proof,
* and route edge cases to manual review without breaking the end-user experience.

<Columns cols={2}>
  <Card title="Security posture" icon="shield-check">
    Onboarding combines time-limited verification codes, identity verification, and wallet ownership proof, which reduces account takeover risk and prevent users from linking accounts they do not control.
  </Card>

  <Card title="Auditability and operations" icon="clipboard-check">
    Each stage produces an explicit status that can be used for reporting and review workflows. Institutions can require manual approval for higher-risk segments without forcing users to repeat steps.
  </Card>
</Columns>

***

## Who does what

<Card title="End user - the institution’s customer" icon="user">
  Verifies email, provides personal details, completes identity verification, and links a wallet account.
</Card>

<Card title="Institution operator - operator of the Levery instance" icon="building-columns">
  Configures email delivery and identity verification, sets activation rules, and determines whether users are approved
  automatically or require compliance review.
</Card>

<Card title="Compliance team - institutional role" icon="people-group">
  Handles exceptions, reviews "under review" cases, and supports operational approval workflows.
</Card>

***

## What the end user should have before starting

The onboarding process is smoother when the user has the following ready:

* Access to the email inbox used for registration.
* Personal details and address information.
* A government ID document (depending on the institution’s KYC requirements).
* A phone available (identity verification is typically easiest on mobile).
* A wallet option (either a new wallet created during onboarding or an existing wallet).

<Callout type="tip" title="Practical tip">
  If identity verification is completed on mobile, the user should keep the Levery application open on desktop and
  return to it after the verification provider finishes.
</Callout>

***

## Step-by-step onboarding (end-user journey)

<Steps>
  <Step title="Verify email with a one-time code">
    Levery begins by verifying email ownership using a **one-time code** delivered to the user’s inbox. This confirms the user can receive communications at the registered address and establishes a reliable identity anchor for notifications, policy updates, and operational follow-ups.

    **What the user does**

    1. Enters an email address in the institution’s Levery application.
    2. Receives a time-limited verification code by email.
    3. Enters the code to confirm control of the address and continue.

    **Why this is secure**

    * Codes are **short-lived** and **cannot be reused** after successful verification.
    * Verification attempts are **limited** to reduce brute-force risk.
    * Resend behavior can be **throttled** to reduce abuse.
    * The platform can avoid revealing whether an email is registered, depending on institutional policy.

    <Callout type="warning" title="Operational note for institutions">
      If users report they are not receiving codes, the first institutional check is outbound email delivery configuration. Levery supports sending OTP emails using the institution’s own SMTP credentials and sender domain, improving deliverability, branding consistency, and audit alignment.
    </Callout>
  </Step>

  <Step title="Provide personal details">
    After email verification, Levery collects the minimum information required to start identity verification and support compliance and reporting needs.

    **Typical information requested**

    * Legal full name.
    * Date of birth (the platform requires adults, 18+).
    * Government ID number (if required by the institution).
    * Residential address details.

    **Why this matters**

    * It ensures identity verification has complete information and reduces back-and-forth.
    * It supports downstream workflows, including review, reporting, and exception handling.
    * It creates a consistent profile record tied to a verified email identity.

    <Callout type="info" title="Data governance note for institutions">
      Levery is designed so that sensitive user information can be stored under strict access controls. Institutions can choose a model where end users can view submitted details but cannot change records outside the onboarding workflow. Compliance roles can be granted controlled visibility for review purposes.
    </Callout>
  </Step>

  <Step title="Complete identity verification (KYC)">
    Identity verification confirms the user is who they claim to be. In Levery, KYC is performed through the provider selected by the institution (for example, Sumsub), following the institution’s configured verification level and jurisdiction requirements.

    **What the user does**

    1. Opens the verification link or scans the QR code provided by the platform.
    2. Completes verification with the provider, often on mobile.
    3. Returns to the Levery application and waits for the status to update.

    **Common status meanings**

    * <Badge>In progress</Badge> The user started verification but has not completed it.
    * <Badge>Approved</Badge> Verification passed and onboarding can continue.
    * <Badge>Under review</Badge> or <Badge>On hold</Badge> Additional review or information is needed.
    * <Badge>Rejected</Badge> Verification failed under the provider’s rules.

    **Benefits for institutions**

    * Institutions can reuse existing KYC vendor relationships, workflows, and risk tiers.
    * Identity checks can be aligned with internal policy, product access rules, and jurisdiction requirements.
    * Verification outcomes can be recorded for audits and compliance operations.

    <Callout type="warning" title="Operational note for institutions">
      Institutions can configure KYC status updates via provider webhooks and also reconcile status when webhooks are delayed. This improves operational stability without exposing complexity to end users.
    </Callout>
  </Step>

  <Step title="Link a wallet and prove ownership">
    After KYC approval, Levery requires the user to link the wallet account that will be used inside the platform. The key security requirement is proof of control. The user must demonstrate they control the wallet they are linking.

    **What the user does**

    1. Connects a wallet (either created during onboarding or an existing wallet).
    2. Reviews a signature request in the wallet interface.
    3. Signs a message to prove control of that wallet account.

    <Callout type="info" title="Important clarifications">
      This is not a transaction. It does not move funds. It does not grant spending permissions. It is a secure ownership proof that binds a verified identity to a wallet account for permissioned access.
    </Callout>

    **Why institutions benefit**

    * It prevents users from registering wallet addresses they do not control.
    * It creates a strong link between identity verification and the account used for regulated access.
    * It improves auditability and supports enforcement for permissioned pools and restricted features.
  </Step>

  <Step title="Activation and review policy">
    Once wallet ownership is confirmed, the institution’s activation policy determines what happens next.

    * If the institution enables **automatic activation**, the user receives access immediately.
    * If the institution requires **manual approval**, the user is placed in a review queue and may see an "under review" message.

    This is a deliberate design choice. Many institutions require more than KYC alone for access, for example additional risk scoring, customer classification, or operational checks. Levery supports these policies without forcing the user to repeat onboarding steps.
  </Step>
</Steps>

***

## Returning later

Onboarding is designed to be resilient:

* The user can refresh the page or return later without losing progress.
* Completed steps are not repeated.
* If a session expires, the user signs in again and onboarding resumes from the next required step.

<Callout type="note" title="Device switching">
  If the user switches devices during onboarding, the email verification and identity verification steps may need to be
  revalidated depending on institutional security settings and session lifetime.
</Callout>

***

## What institutions can configure

Institutions can tailor onboarding controls to match internal security standards, deliverability practices, and compliance workflows.

<Card title="Email delivery for one-time codes" icon="send">
  Institutions can send verification codes using their own SMTP credentials, sender domain, and branded messaging. This
  improves deliverability, reduces phishing confusion, and aligns onboarding communications with existing customer
  policies.
</Card>

<Card title="KYC provider and verification level" icon="fingerprint">
  Institutions can connect their own identity verification provider credentials and configure verification levels by
  region, product, or risk tier. This keeps the onboarding experience consistent while meeting jurisdiction
  requirements.
</Card>

<Card title="Activation policy" icon="building-shield">
  Institutions can choose automatic activation after verification or staged, manual activation for higher-control
  environments. This supports workflows that require internal approvals or additional risk checks.
</Card>

***

## Support guidance

When onboarding issues occur, the most common institutional checks are:

* Outbound email delivery configuration (SMTP and sender domain).
* KYC provider configuration and connectivity (including webhook delivery and status reconciliation).
* Activation policy (automatic approval vs review queue).

<Callout type="success" title="Support tip">
  When escalating an onboarding issue, institutions typically ask end users to provide their registered email and the
  wallet address they attempted to link. This helps support teams identify the relevant record quickly while keeping the
  process consistent and auditable.
</Callout>