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

# The identity handoff

> How a patient verifies their identity on the platform, what the handoff link carries, and how your servers learn the result.

The platform hosts the page where a patient proves who they are. Your storefront never renders a
camera, never handles a photo of an ID, and never holds a verification credential — it hands the
patient to the hosted identity step with a link, exactly the way it hands them to checkout, and your
servers learn the result afterwards. This page describes that handoff: the entry URL, what the link
carries, and the read that tells you what happened.

Identity capture is sensitive and compliance-laden, so it lives in one hardened place under the
platform's own origin — never scattered across storefronts. This is the same rule as the checkout
door: the standard, high-stakes steps are platform-hosted, and your site hands off to them.

<Tip>
  **You do not build this step.** The same site kit that builds your storefront ships the hand-off
  that brings a patient here. Its link composer builds the identity handoff alongside the checkout
  handoff — carry the patient's enrollment reference and the platform does the rest. Fork a tagged
  release, brand it, and the handoff is already wired.
</Tip>

## The entry link

The hosted identity step lives at `/identity` on the platform's patient portal — the same origin
where your patients sign in and manage their plan. The link carries its context as query
parameters:

| Parameter    | When            | What it is                                                                                                                             |
| ------------ | --------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `journey_id` | Always required | The patient's enrollment reference (`jny_...`). A link without a valid one is refused with a plain explanation — nothing is submitted. |
| `client_ref` | Optional        | Your deployment reference, when your program is set up to route by it.                                                                 |
| `return_to`  | Optional        | A path on the patient portal to send the patient to once they are verified.                                                            |

`journey_id` is the only parameter the link must carry. The therapy the checks run for is **not**
on the link — the platform resolves it from the enrollment the `journey_id` names, so you never
pass it and a link cannot assert it.

The link carries context only — never a result. A link cannot assert that a patient is verified;
the platform decides that from the photo the patient takes on the hosted page, and a link that tries
to claim otherwise is ignored.

## What the patient does

On the hosted page the patient takes a clear photo of their government ID — with the platform's own
camera, or by uploading one — and confirms the name on it. There is no app to install and no vendor
screen to trust; the capture is the platform's, under the platform's origin. The platform then runs
the check and returns one of three honest outcomes:

* **Verified.** Identity is confirmed and linked to the enrollment. The patient continues — to the
  path you set in `return_to`, or to their account.
* **Try again.** The photo could not be read clearly. The patient retakes it; nothing is held
  against them.
* **Under review.** The check needs a person to confirm it by hand. The patient is told plainly,
  emailed the moment it clears, and asked for nothing more in the meantime.

## The ID photo never touches your code

The standing rule, stated plainly: **no photo of an ID is ever handled in your storefront.** Capture
happens on the hosted page; the image travels from the patient's browser to the verification service
through the platform, and never passes through you. There is no camera for you to build, no image
for you to relay, and nothing identity-shaped for you to store.

## How your servers learn the result

The patient continues inside the portal after verifying — there is no browser redirect back to your
storefront, and the result never rides the patient's browser to reach you. Your servers read it from
the enrollment: `GET /v1/journeys/{journey_id}/status` returns the patient's public enrollment
status, and a patient never shows as ready for clinical review before their identity clears — so the
enrollment read is safe to drive your storefront's own status copy.

Verification never gets its own status value. It is one of the
[quiet steps](/pages/integrate/the-patient-flow#the-status-vocabulary): a patient
mid-verification keeps whatever status they already had, and the value moves when the
enrollment moves, not when the ID check does. So an integration that waits here for a
verification-shaped status change will wait forever — and it may not see a status value at all,
because this read may return
[no status yet](/pages/integrate/the-patient-flow#when-a-status-is-not-yet-reportable)
instead. Follow the enrollment, not the ID check.

One fact worth designing around: a patient whose ID is under review is not stuck and not lost. The
manual check runs on the platform and the patient moves forward the moment it clears — no action is
needed from your side.