# User onboarding

Source: https://docs.settlemint.com/docs/user-guides/runbooks/onboard-user-im
Complete workflow to register a user in the identity registry and issue KYC verification.



This guide walks Identity Managers through the complete user onboarding workflow. It covers the steps after a user has created their account and wallet through the [User Onboarding](/docs/user-guides/user-management/user-onboarding) process. To complete all steps in this runbook, you will need both the **Identity Manager** and **Verification Issuer** roles.

## Prerequisites [#prerequisites]

* **Identity Manager** role for registry registration
* **Verification Issuer** role for issuing KYC verifications
* Must be configured as [trusted issuer](/docs/user-guides/compliance/configure-trusted-issuers) for KYC topic
* User must have completed onboarding with on-chain identity

## About the onboarding workflow [#about-the-onboarding-workflow]

As an Identity Manager, you complete two key steps to fully onboard a user:

1. **Register in identity registry** - Add the user to the on-chain registry with their jurisdiction
2. **Issue KYC verification** - Attest that you have verified the user's identity

### User states [#user-states]

| State                    | Description                                   | Can receive assets     |
| ------------------------ | --------------------------------------------- | ---------------------- |
| **Pending Registration** | User completed onboarding but not in registry | No                     |
| **Registered**           | Added to registry, awaiting verification      | Depends on asset rules |
| **Verified**             | Has required KYC verification                 | Yes                    |

## Onboarding steps [#onboarding-steps]

<Steps>
  <Step>
    ### Verify user readiness [#verify-user-readiness]

    Before starting, confirm the user has completed their onboarding:

    1. Navigate to **Participants** > **Users**
    2. Find the user and check their status
    3. Verify they have an **Identity address** assigned

    If the user shows no identity address, they haven't completed onboarding yet. See [User Onboarding](/docs/user-guides/user-management/user-onboarding) for what the user needs to complete.

    ![User list showing identity address column](/docs/runbooks/onboard-user-im-user-list.webp)
  </Step>

  <Step>
    ### Register in identity registry [#register-in-identity-registry]

    Registration adds the user to the on-chain identity registry with their jurisdiction.

    **Follow [Register User](/docs/user-guides/user-management/register-user) to:**

    * Select the user from the Users list
    * Click **Register Identity**
    * Choose the appropriate jurisdiction based on user documentation
    * Complete the registration transaction

    <Callout type="info" title="Jurisdiction selection">
      Choose based on the user's legal residence or incorporation. This determines applicable compliance rules.
    </Callout>

    After transaction confirmation, verify the user status changed to &#x2A;*"Registered"**.

    ![User profile showing Registered status](/docs/runbooks/onboard-user-im-registered.webp)
  </Step>

  <Step>
    ### Issue KYC verification [#issue-kyc-verification]

    With the user registered, issue a KYC verification to attest their identity.

    **Follow [Verify KYC](/docs/user-guides/compliance/verify-kyc) to:**

    * Access the user's profile and click **Manage verifications**
    * Click **Issue verification**
    * Select &#x2A;*Know Your Customer (KYC)** topic
    * Complete the verification transaction

    <Callout type="info" title="Trusted issuer status">
      A green shield next to the verification confirms you are a trusted issuer for KYC. Without trusted issuer status, your
      verification won't satisfy compliance requirements.
    </Callout>

    ![Verification list showing KYC with green shield](/docs/runbooks/onboard-user-im-kyc-verified.webp)
  </Step>

  <Step>
    ### Verify completion [#verify-completion]

    After issuing the KYC verification:

    * User appears with verified status
    * User can now receive assets that require KYC verification
    * Additional verifications may be needed depending on asset-specific compliance rules

    ![Fully verified user profile](/docs/runbooks/onboard-user-im-complete.webp)
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

| Issue                                 | Solution                                                                      |
| ------------------------------------- | ----------------------------------------------------------------------------- |
| Cannot see Register Identity button   | Verify you have Identity Manager role and user has on-chain identity          |
| Registration transaction fails        | Check wallet has sufficient gas and correct user is selected                  |
| Cannot see Issue verification button  | Verify you have Verification Issuer role and are configured as trusted issuer |
| Verification not showing green shield | Confirm you're a trusted issuer for KYC topic                                 |
| User still cannot receive assets      | Check asset-specific compliance requirements beyond KYC                       |

## Related guides [#related-guides]

* [User Onboarding](/docs/user-guides/user-management/user-onboarding) - Understanding the user's onboarding flow
* [Provide KYC Data](/docs/user-guides/user-management/provide-kyc-data) - How users complete their KYC profile
* [Manage KYC Data](/docs/user-guides/compliance/manage-kyc-data) - Review and approve KYC submissions
* [Register User](/docs/user-guides/user-management/register-user) - Detailed registration reference
* [Verify KYC](/docs/user-guides/compliance/verify-kyc) - Detailed verification reference
* [Configure Trusted Issuers](/docs/user-guides/compliance/configure-trusted-issuers) - Set up verification permissions
* [Compliance Overview](/docs/user-guides/compliance/overview) - Understanding verification framework