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