> For the complete documentation index, see [llms.txt](https://docs.ur.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ur.app/concepts/overview-the-user-lifecycle.md).

# The user lifecycle

To access the full range of core banking operations, a user must hold a [URID](/concepts/urid.md) in the `Live` state. Onboarding is a single KYC flow that takes a newly minted URID from `Tourist` (minted, before KYC) to `Live` (KYC passed). This page describes the account states, how a user moves between them, and what your platform is responsible for along the way.

For what UR verifies during KYC and the methods it uses (questionnaire, proof of address, NFC scan, liveness, AML screening), see [KYC & compliance](/concepts/kyc-and-compliance.md).

## User states

Every URID carries an on-chain account status, and that status controls what the user can do. The values are the `AccountStatusV2` enum; for the on-chain mapping, see [Smart contracts](https://docs.ur.app/api-reference/smart-contracts). The states are the following:

| Status        | Value | How the user reaches it                                        | What the user can do                                                                                              |
| ------------- | ----- | -------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| `Na`          | 0     | New user; URID not yet minted                                  | Nothing yet                                                                                                       |
| `Tourist`     | 2     | URID is minted, before KYC                                     | Receive partner off-ramp and inbound P2P (up to 250 USD/EUR); cannot move funds externally, hold an IBAN, or send |
| `Live`        | 5     | Completes KYC and passes compliance review                     | All banking features: external deposits (IBAN), external payouts, send and receive P2P, FX, card                  |
| `SoftBlocked` | 1     | An ongoing task (CRS, ongoing KYC, or EDD) passed its deadline | Money features locked until the open task is completed; recoverable to `Live`                                     |
| `Blocked`     | 3     | A compliance action freezes the account                        | Account frozen                                                                                                    |
| `Closed`      | 4     | The account is closed                                          | Terminal; no access                                                                                               |

{% hint style="info" %}
`Tourist` is not a KYC stage the user completes. It is the state a URID is minted into before KYC. There is one KYC flow, and passing it moves the user straight to `Live`. Functions for any non-`Live` status are restricted on-chain.
{% endhint %}

## State transitions

A URID is always minted in `Tourist` and promoted to `Live` once KYC passes; there is no direct path from `Na` to `Live`.

```mermaid
flowchart LR
    Na["Na (0)"] -->|mint URID| Tourist["Tourist (2)"]
    Tourist -->|KYC passed| Live["Live (5)"]
    Live -->|ongoing task overdue| SoftBlocked["SoftBlocked (1)"]
    SoftBlocked -->|task completed| Live
    Live -->|compliance action| Blocked["Blocked (3)"]
    Blocked --> Closed["Closed (4)"]
```

A user whose KYC is rejected stays in `Tourist` and cannot access core banking features. `Blocked` and `Closed` can also be reached from other states by a compliance action.

## What you handle vs UR

Onboarding responsibilities split as follows:

| Step             | UR handles                                                           | You handle                                                                          |
| ---------------- | -------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| KYC verification | Identity checks, screening, compliance review                        | Presenting KYC components in your app (UR webview or Sumsub SDK)                    |
| Wallet creation  | Minting the URID NFT, provisioning the wallet (Managed Custody Mode) | Mapping your user ID to their URID                                                  |
| State changes    | Transitioning the URID between statuses                              | Listening for webhooks, updating your UI accordingly                                |
| KYC prompt       | Nothing; you decide when                                             | Prompting the user to complete KYC when they attempt an action that requires `Live` |

## The onboarding flow

A URID moves from `Tourist` to `Live` through a single KYC flow. The steps run in this order:

{% stepper %}
{% step %}

### URID is minted (Tourist)

The user authenticates, and UR mints the URID NFT in `Tourist` status. The user can receive partner off-ramp and inbound P2P (up to 250 USD/EUR), but cannot move funds externally.
{% endstep %}

{% step %}

### Proof of address

The user confirms their residential address through the Sumsub flow (GPS method).
{% endstep %}

{% step %}

### Questionnaire

The user answers the questionnaire (eligibility, source of funds, declarations) through the Sumsub flow.
{% endstep %}

{% step %}

### Proof of identity

The user completes the passport or national ID NFC scan and a liveness check through the Sumsub flow. See [KYC components](#kyc-components) for the mobile NFC requirement.
{% endstep %}

{% step %}

### Form A signing

Outside Sumsub, the user signs the Beneficial Ownership Declaration (Form A) with the embedded wallet that holds their URID.
{% endstep %}

{% step %}

### Compliance review

UR screens the user (sanctions, PEP, adverse media) and reviews the submitted data. On pass, the URID moves to `Live` and all account restrictions are lifted automatically. On failure, the attempt is rejected and the user stays in `Tourist`.
{% endstep %}
{% endstepper %}

Your backend tracks progress through a KYC status field whose exact values depend on the integration path: `kycFlow.currentStep` on the UR main stack (see the [External Wallet Access Mode API reference](https://docs.ur.app/api-reference/account/external-wallet-access-mode)), or the session `state` in the partner-managed SDK path (see the [Managed Custody SDK KYC reference](https://docs.ur.app/api-reference/kyc-and-kyb/managed-custody-sdk-kyc)).

### Webhooks you receive

You receive the following onboarding webhooks. For money-movement and other events, see the full [event catalog](/developer-resources/webhook.md#6-event-catalog).

| Webhook event            | When                                                                                           | Applies to                     |
| ------------------------ | ---------------------------------------------------------------------------------------------- | ------------------------------ |
| `sumsub_kyc_result`      | A Sumsub review completes (`Pass` or `Rejected`)                                               | All KYC paths                  |
| `kyc_status`             | UR returns the compliance decision (`Pending`, `Pass`, `Rejected`, `ManualReview`, or `Error`) | All KYC paths                  |
| `fma.account.result`     | Partner-managed onboarding ends (`activated` or `rejected`)                                    | Partner-managed (FMA) KYC only |
| `fma.penny_drop.result`  | A penny-drop attempt resolves (`verified` or `failed`)                                         | Partner-managed (FMA) KYC only |
| `fma.kyc.retry_required` | UR ops request a partner-driven retry                                                          | Partner-managed (FMA) KYC only |

{% hint style="info" %}
The definitive `Tourist → Live` signal is `kyc_status` with `status: "Pass"` on the UR main stack, or `fma.account.result` with `status: "activated"` for partner-managed KYC. Only raise the user's access level on that signal.
{% endhint %}

## KYC components

The KYC flow collects four components, presented in the order shown in [The onboarding flow](#the-onboarding-flow). Depending on your integration mode, you present them through the UR webview or the Sumsub SDK.

**Proof of address.** UR uses the GPS method to confirm the user's residential address. UR can show this through a webview or iFrame pointing to the UR web app (get.ur.app). The user must be signed in.

**Questionnaire.** Questions about the user, including eligibility screening, source of income, and monthly income. For a lightweight integration, UR can show the questionnaire through a webview or iFrame pointing to get.ur.app. The user must be signed in.

**Proof of identity (passport or national ID NFC scan).**

{% hint style="warning" %}
**NFC scanning is only available on a mobile app.** If your platform uses the Sumsub SDK directly (External Wallet Access Mode), the NFC scan step is only supported in the Sumsub mobile SDK (iOS/Android); it is not available in the Sumsub web SDK. You must expose this step through your mobile app. Web-only platforms cannot complete this step through the Sumsub SDK. If your platform has no mobile app, email <support@ur.app> to discuss alternatives.
{% endhint %}

* Scenario A1 (iOS): UR returns a QR code and link to its NFC scanning provider. When the user taps it, an iOS App Clip opens, the user completes the NFC scan, then returns to your app.
* Scenario A2 (Android): UR returns a QR code and link to its NFC scanning provider. The user downloads a separate app to perform the NFC scan, then returns to your app.

**Agreement (Form A) signing.** Form A contains the information the user filled in during KYC, so the user must complete the proof of address and questionnaire first and the data must exist in UR's database before UR can generate the form. The user signs Form A with the embedded wallet that holds their URID. UR can show Form A through a webview pointing to get.ur.app. The user must be signed in.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.ur.app/concepts/overview-the-user-lifecycle.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.