The patient flow - Purple Label MD

A patient’s enrollment is one continuous flow: they arrive on your storefront, answer the intake questionnaire, sign in, verify their identity, pay, and a clinician reviews the case — then the order ships. Your storefront never drives that flow; it observes it through one read and a webhook stream, and surfaces the platform’s answer to the patient. This page walks the stages end-to-end, defines the eleven status values, and covers the other documented outcomes this read can return.

The stages, end to end

Arrival. The patient lands on your storefront and starts an enrollment — through an entry link or your own headless start. An enrollment id (jny_...) exists from this first step, and the status read accepts it right away — but a status value is not the only documented outcome. The read may instead return no status yet, so do not assume a status value on the first read.
The intake questionnaire. The server serves the questionnaire one question at a time; the patient answers until it is complete.
Sign-in and identity. The patient signs in (passwordless) and proves their identity on the hosted identity step. Neither step changes the public status — a patient mid-verification simply keeps the status they had.
Payment. The patient pays through the checkout door. Where this step sits is configured per program — see the ordering note below.
Clinical review. A licensed clinician reviews the completed case and decides. Your storefront never announces an outcome before the review returns it.
Fulfillment. An approved order is prepared, shipped, and delivered. The vocabulary carries these stages so your handling is complete; enrollments begin reporting them when shipment tracking arrives on the platform.

Read the status

One endpoint tells you where a patient is: GET /v1/journeys/{journey_id}/status.

curl "$BASE_URL/v1/journeys/jny_31f8k2/status" \
  --header "Authorization: Bearer $TEST_API_KEY" \
  --header "X-Brand-Id: $BRAND_ID"

{
  "journey_id": "jny_31f8k2",
  "public_status": "IN_REVIEW",
  "status_version": "v1"
}

Identifiers and a status value only — never patient data, never an answer, never a clinical detail. The read is a pure view: calling it changes nothing, and nothing on the platform ever uses it as an input. Poll it as often as you like, or let webhooks tell you when to re-read.

When a status is not yet reportable

A 200 carrying public_status is not the only documented outcome of this read. It sits alongside the refusals every key-authenticated call can return — 401 when the key is missing or not valid, 404 when the enrollment is unknown or not yours, 400 on a malformed id — plus two more the contract declares specifically for this read. Keep your normal authentication and error handling; what follows is in addition to it, not a replacement for it. 422 — a typed “no status yet” response. When the platform has no status to report for an enrollment, this read returns 422 instead of a status value. The type is a stable, machine-readable token, and you can branch on it today:

https://purple.md/problems/journey-status-pending

The platform currently returns it with this body:

{
  "type": "https://purple.md/problems/journey-status-pending",
  "title": "Enrollment status not yet available",
  "status": 422,
  "detail": "This enrollment exists — it was started through the hosted intake experience under your brand. Reporting live status for enrollments started there is a declared platform capability that is not yet in service, so no status can be returned for it yet. Retrying this read will not change the answer; once the capability ships, this same read will return the status."
}

That detail is the platform describing the situation it is in at the time of the call. Branch on the type; read detail as explanation, not as a promise this page is making to you — the circumstances a 422 covers can change, and the type is the part that stays stable. Two things to design around:

It is not a failed call and not a missing enrollment. Your request was well-formed and the enrollment is yours. Do not treat it as a 404, and do not surface it to the patient as an error.
The body carries nothing patient-specific — no enrollment id, no brand, no detail about the person — so nothing in it can be read as information about a particular patient.

Treat 422 as a state your storefront can sit in: show that enrollment status is currently unavailable, and do not infer clinical progress or completion from it — a missing status is not evidence of movement. Re-read with bounded backoff rather than in a tight loop — the body above tells you a retry will not change the answer, so re-reading is how your integration notices a later change of state, never a way to force one. 503 — the read itself did not succeed. The status source was unavailable, so the platform could not tell you where the enrollment is. This says nothing about the enrollment — it may have moved on, it may not have. Retry with backoff, and never treat the absence of an answer as an answer.

The status vocabulary

When the read answers 200, public_status is one of exactly eleven values. Each value is stable within v1 — if a value’s meaning ever needs to change, the platform publishes a new status_version rather than quietly editing this one, so your handling can never be silently invalidated.

Status	The patient is…	What your storefront does
`RECEIVED`	Started — the enrollment exists and intake is underway or just submitted.	Show progress; nothing is decided yet.
`IN_REVIEW`	Waiting on the platform — the case is with the clinical review, or has cleared it and the order is not yet authorized.	Show “in review”; no action from the patient.
`ACTION_NEEDED`	Needed — the review needs something more from the patient, or they dropped off mid-flow.	Bring the patient back in; the platform has told them what it needs.
`APPROVED`	Approved — the review cleared the case and the order is authorized.	Show the approval.
`DECLINED`	Declined — the review did not clear the case.	Show the outcome plainly; the platform has communicated the decision to the patient.
`ON_HOLD`	Paused — the review put the case on hold.	Show a holding state; no patient action unless the platform asks.
`PREPARING`	Approved and in the pharmacy’s hands — the order is being prepared.	Show fulfillment progress.
`SHIPPED`	Shipped — the order is on its way.	Show shipment progress.
`DELIVERED`	Delivered — the order arrived.	Close the loop.
`SUPERSEDED`	Replaced — a newer decision on this patient replaced this one.	Follow the patient’s current enrollment instead.
`REFILL_DUE`	Due — the plan has a refill coming up.	Prompt the patient if your program surfaces refills.

Two rules of the vocabulary worth designing around:

The status never runs ahead of the money. A patient never shows APPROVED before their order is actually authorized — so “approved” on your storefront always means a real, backed order, never a prediction.
Quiet steps stay quiet. Sign-in, identity verification, and a completed payment do not have their own statuses — the enrollment keeps its current value through them. If you need payment-level detail for an order, read the payment status endpoint instead.

Where the payment step sits

By default a patient finishes the questionnaire first and pays afterwards, before the clinical review — the sequence the how it works guide describes. Programs can instead be configured pay-first, where payment is collected before the questionnaire begins. The ordering is a per-program setting, arranged with your onboarding contact — it can be set for your whole account or for a single offering, and the more specific setting wins. Three facts hold either way:

Each enrollment picks its ordering once, at its start, and keeps it — a configuration change never reshuffles a patient already in flight.
The clinical and identity safeguards are identical in both orderings — pay-first changes when the card is collected, never what the review requires.
A payment is never a decision. Paying first does not advance the public status past the review; the case still shows IN_REVIEW until the clinician decides.

Watching without polling

Every status change also reaches you through webhooks: register an endpoint, receive the reference-only event, and re-read the status endpoint for the current value. The walkthrough wires this end to end.

​The stages, end to end

​Read the status

​When a status is not yet reportable

​The status vocabulary

​Where the payment step sits

​Watching without polling