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

# Hosted

> Having the person being verified provide their own documents, on our screens.

For a workflow whose `mode` is `hosted`. You create a verification with the person's mobile number
and send them in; they sign in with that number, work through the steps your workflow configures, and
we send them back to your `return_url`. You never handle their documents.

If the documents already reached you through your own onboarding, that is a staged workflow: see
[Staged](/verification/staged). The mode belongs to the workflow, not to the
verification, and creating one on a hosted workflow without a `mobile` is refused with `400`.

## Two ways in

A journey has two entrances. Which one you use depends on how the user arrives, not on what the
workflow asks for: the steps, the record, and the redirect back to your `return_url` are the same
either way.

| | [A link you send](#a-link-you-send) | [A handoff you open](/verification/handoff) |
| - | - | - |
| Where you get it | `journey_url`, on every record | `POST /verifications/{verification_id}/handoff` |
| How the user proves who they are | They sign in with the mobile number you created the verification with | Your app already did it, so they sign in to nothing |
| How long it lasts | As long as the verification does | One use, and `expires_in_seconds` |
| Who it lets in | Any user of that workflow, as themselves | The one user of that verification |
| Safe to store, log, or forward | Yes, it carries no credential | No, the whole URL is a credential |
| Reach for it when | You message the user: WhatsApp, SMS, email, a QR code | The user is already inside your own app |

## A link you send

`journey_url` comes back on every read of the record. It is one fixed address per workflow, so you can
template it into a WhatsApp message, print it on a QR code, or paste it into an email, and it keeps
working for as long as the verification does.

```json The record, abridged theme={"system"}
{
  "id": "3f2504e0-4f89-41d3-9a0c-0305e82c3301",
  "journey_url": "https://verify.privue.ai/acme/merchant-onboarding"
}
```

The user signs in there with the mobile number you passed to `POST /verifications`, which is also what
makes the address safe to send over any channel. Only a number you have created a verification for can
sign in, and each one reaches only their own journey, so the link is not worth guarding and is worth
nothing to anyone else. A user can come back to it as often as they like, from whichever device they
happen to be holding.

For a user who reaches the journey from inside your own app and has already signed in to you, open it
with a handoff instead: see [Handoff](/verification/handoff).

## Return URL and redirect

`return_url` is optional. Where you give one, the journey sends the user there when they submit, with
two query parameters appended:

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

Your own query parameters on the `return_url` are preserved.

A journey a [gate check](/verification/step-types#gate-check) stops is not sent there. Only a
`redirect` your system answers the check with sends the person anywhere, and only to a URL registered
for the workflow.

<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>

A `return_url` must match one of the URLs registered for **the workflow you are creating on**, and
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.

The allowlist belongs to the workflow rather than to your account, so each of your journeys returns
users to its own URLs and a `uat` workflow can send them somewhere else entirely. A workflow with no
URLs registered takes no `return_url` at all.


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