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

# Verification lifecycle

> Statuses, identifiers, timestamps, and the redirect back to your app.

## Statuses

A verification moves through a small, durable set of states. There is no expiry: a user can return to
an unfinished verification at any time.

| Status        | Meaning                                               | Set when                                       |
| ------------- | ----------------------------------------------------- | ---------------------------------------------- |
| `created`     | Started, but the user has not opened the flow yet.    | `POST /verifications`                          |
| `in-progress` | The user has opened the flow and is completing steps. | First time they sign in                        |
| `completed`   | The user reviewed and submitted. Data is final.       | User submits                                   |
| `cancelled`   | Ended early and accepts no further input.             | `POST /verifications/{verification_id}/cancel` |

## Creating a verification

`POST /verifications` is **idempotent per phone**. The same phone number for your organization always
resolves to the same `verification_id`, so a retry replays the existing verification instead of creating a
duplicate. You can safely call it again with the same number.

The `return_url` you send must be on the allowlist we registered for you, or the call is rejected with
`400`. See [Return URL and redirect](#return-url-and-redirect) below.

## Identifiers

| Field             | Owner  | Purpose                                                                                          |
| ----------------- | ------ | ------------------------------------------------------------------------------------------------ |
| `verification_id` | Privue | Names the verification on every read. Use it as the key.                                         |
| `reference_id`    | You    | Your own optional correlation id (up to 128 chars). Stored and echoed back, never used as a key. |

## Timestamps

Timestamps are in IST. A verification carries `created_at`, and `opened_at` / `submitted_at` /
`cancelled_at`, each null until the matching transition happens.

## Return URL and redirect

When the user finishes, we redirect them to your `return_url` with two query parameters appended:

```
https://yourapp.com/kyc/done?verification_id=3f2504e0-4f89-41d3-9a0c-0305e82c3301&status=completed
```

<Warning>
  These parameters render a landing screen. They are **not signed and not proof** of the outcome.
  Always confirm the real result by polling the API with the `verification_id`.
</Warning>

Allowlist matching is strict: the scheme and host must match exactly, the path must sit at or under an
allowlisted path on a segment boundary, and only `https` is accepted (plain `http` is allowed only for
`localhost` during integration).

## Ending or restarting

| Action | Endpoint                                       | Effect                                                                                        | Allowed from                          |
| ------ | ---------------------------------------------- | --------------------------------------------------------------------------------------------- | ------------------------------------- |
| Cancel | `POST /verifications/{verification_id}/cancel` | Ends the verification. Idempotent.                                                            | `created`, `in-progress` (else `409`) |
| Reset  | `POST /verifications/{verification_id}/reset`  | Clears all steps and uploaded documents and returns it to `created`, so the user starts over. | Any status, including terminal ones   |

Reset is how you revive a `cancelled` or `completed` verification rather than stranding it.