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

# Verification requests and links

> Every verification is a request with a link. How requests are created and delivered, link lifetimes, statuses, review, and what the verification page needs from browsers and devices.

This page is for administrators, help desk leads and developers who need to know what happens to a verification after it's sent. When you finish you will know how a request moves through its statuses, how long links last, and what employees' devices need.

## What a request is

A verification request is the record of one verification: who is being verified, for which use case, which flow ran, what the person has completed so far, and the outcome. Every verification produces one, whether an agent, a connector, the self-service portal or an API call started it. You see requests in the help desk app, in **Activity**, and through the API.

## How a request is created and fulfilled

1. **Something starts it** for one person in your directory and one [use case](https://docs.truu.ai/idv/use-cases/overview.md).
2. **The use case picks the flow** from the person's directory groups.
3. **A link is delivered** by email or text to a contact on file, or copied and handed over by whoever created it. An agent can send to a different address or number when needed.
4. **The person completes the flow** on the verification page, Primary column first, with fallbacks when needed.
5. **The outcome is recorded** and shown live to whoever started it.

## Link lifetime and reuse

| Use case | Link lifetime |
| - | - |
| Helpdesk | 30 minutes |
| Credential reset | 1 hour |
| Onboarding | 7 days |
| Verification (none named) | 30 minutes |

* **Active links are reused.** Sending a link for a person and use case that already has an active link re-delivers the same link with a fresh expiry. A person never holds two competing links for the same thing.
* **Runs start on Begin.** A run is counted when the person taps **Begin**, not when they open the link, so previewing costs nothing. See [Retries](https://docs.truu.ai/idv/build/flows.md#retries).

## Statuses

| Status | Meaning | Final |
| - | - | - |
| **Pending** | The link was created and delivered; the person hasn't started. | No |
| **In progress** | The person tapped **Begin** and is completing steps. | No |
| **Needs review** | The verification went to manual review: the person asked for it, or the runs were used up with review turned on. A reviewer approves, rejects or sends it back. | No |
| **Verified** | Every factor in one column passed, or a reviewer approved it. | Yes |
| **Failed** | A factor failed and no runs are left, or a reviewer rejected it. | Yes |
| **Declined** | Stopped for a hard failure, such as a fraud signal or a proofing vendor declining the ID. It can't be retried. | Yes |
| **Expired** | The link's lifetime ended before completion. | Yes |
| **Cancelled** | An agent or API caller cancelled it. | Yes |

In the help desk app, the tabs are **All**, **Active** (Pending and In progress), **In review** (Needs review), **Verified** and **Ended** (Failed, Declined, Expired and Cancelled).

```mermaid theme={null}
stateDiagram-v2
    [*] --> Pending : link delivered
    Pending --> InProgress : person taps Begin
    InProgress --> Verified : a column passes
    InProgress --> NeedsReview : review requested or runs used up
    NeedsReview --> Verified : reviewer approves
    NeedsReview --> Failed : reviewer rejects
    NeedsReview --> InProgress : reviewer sends back
    InProgress --> Failed : no runs left
    InProgress --> Declined : hard failure, such as a fraud signal
    Pending --> Expired : lifetime ends
    InProgress --> Expired : lifetime ends
    Pending --> Cancelled : cancelled
    InProgress --> Cancelled : cancelled

    state "In progress" as InProgress
    state "Needs review" as NeedsReview
```

> [!WARNING]
>
> Gate any downstream action on **Verified** only. In progress is not verified, and a failed request followed by a second attempt isn't verified until a request for that person reaches Verified.

### What agents should do

* **Pending for more than a minute or two** usually means the link went somewhere the caller can't reach right now. Check the channel it went to ; resend, or copy the link.
* **Failed:** follow your escalation procedure. Don't fall back to informal questions.
* **Declined:** treat it as a possible impersonation attempt. Don't send another link to the same caller; follow your escalation procedure.
* **Expired** requests can't be resumed. Send a new one if the caller is still there.
* **No longer needed?** Cancel it. The link stops working immediately.

## What the record holds

Each request records the person, who or what started it and when, the use case and flow, each factor attempted with its outcome and reason, which directory attribute served each factor, the column that completed, a timestamp for each step, and the result. One-time codes, knowledge answers and captured images aren't on the record. See [Data handling](https://docs.truu.ai/idv/security/data-handling.md).

## The verification page

The link opens TruU's verification page, branded with your logo and colors (see [Branding](https://docs.truu.ai/idv/build/branding.md)). No app is installed.

### Browsers

| Platform | Browsers | Notes |
| - | - | - |
| iPhone and iPad | Safari, Chrome | Open links in the default browser, not an in-app browser inside a mail or chat app, so the camera can be allowed |
| Android | Chrome, Samsung Internet | Same note on in-app browsers |
| Windows | Edge, Chrome, Firefox | Camera steps work but are less reliable than phones |
| macOS | Safari, Chrome, Firefox | Camera steps work but are less reliable than phones |

The current and previous major versions are supported, with JavaScript, cookies and camera access allowed for `verify.truu.ai`.

### Phone versus desktop

Plan around phones. Face and ID checks need a good camera, and laptop webcams often loop on "move closer" or never start, while phone cameras also focus on ID documents. Codes and knowledge questions work on any device. Badge needs a reader attached to the device.

When someone opens a link on a computer, camera steps offer a QR code to continue on their phone; with **Phone camera only** on, the QR code is the only option. The phone takes over the same session and the computer updates when it finishes.

### Camera and accessibility

* Camera permission for `verify.truu.ai`. The browser asks on first use; on managed devices, browser policy can pre-grant it.
* Even lighting. The page gives framing prompts but can't fix a backlit face or glare on an ID.
* Every non-camera step works with a keyboard and screen reader, and text follows the device's font size. For people who can't complete camera steps, keep a non-camera column in the flow and make sure agents know about **Try another way**.

### Network

Phones on cellular need nothing from you. For computers behind a proxy and for shared devices, allow outbound HTTPS to `verify.truu.ai` and `agent.truu.ai`, plus the proofing vendor and face liveness hosts, and exclude them from TLS inspection, which breaks camera streams. See [Network requirements](https://docs.truu.ai/idv/security/network.md).

## Related

* [How use cases work](https://docs.truu.ai/idv/use-cases/overview.md)
* [Agent guide](https://docs.truu.ai/idv/help-desk/agent-guide.md)
* [API quickstart](https://docs.truu.ai/idv/api/quickstart.md)


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