How intake serving works - Purple Label MD

How it works introduces the three sockets your storefront connects to. This page goes one level deeper on the first of them: how the intake questionnaire is actually served, step by step, and exactly what your renderer is — and is not — responsible for.

One loop, two calls

The whole protocol is a loop over two endpoints:

GET /v1/instrument/resolve starts a session — or resumes one — and returns the first step.
POST /v1/instrument/next submits the answer to the question the session is on and returns the next step.
Repeat until the response carries status: complete.

There is no “finish” call. Completion is a status the server declares once every required answer is in — never something the client computes or asserts.

The server is the sole authority

Your storefront can keep its own logic for polish — preloading a likely next screen, animating a transition. Treat that logic as advisory only. The server alone decides which question comes next, which questions are visible, and when the questionnaire is finished. The only way to advance is to submit an answer and render what comes back. There is no client-side path around a required question, no reordering, and no early exit into complete — whatever a browser extension, a cached page, or a bug in your code does, the served flow holds.

One session, two identifiers

session_id is the handle for this run of the questionnaire. Every next and abandon call carries it.
journey_id (prefixed jny_) is the patient’s enrollment id, minted by the server on the first resolve. Send it back in the X-Journey-Id request header on a later resolve to resume: the patient gets a fresh session with everything they already answered applied, so nothing is asked twice. That header is how the hosted platform threads the patient’s context — see Identifiers and error types. It is also the id you will see again on webhook events and the enrollment status read.

Anatomy of a step

Every response in the loop — from resolve, next, and abandon alike — is the same shape: the current step.

Field	What it carries
`session_id`, `journey_id`	The session identity, as above
`status`	`active` (a node is presented), `complete`, `abandoned`, or `blocked` (the server ended the questionnaire, for example because a required consent was declined). Keep submitting only while it is `active`
`node`	The node to present now; `null` when the session is finished or `blocked`
`blocked`	The stop, present only when `status` is `blocked`: a reason `code` (treat an unknown code as a generic stop), the `node_id` where it stopped, and optional served `content` to show
`flags`	Advisory markers, such as a detected mismatch between the validated shipping state and the state the patient asserted
`issues`	Validation problems with the answer just submitted — present on a rejected answer
`handoff`	The post-completion hand-off, present only once `status` is `complete` and only when the session began from an entry link

The rendered question

The node object is presentation only — everything about what the question means stays on the server. Your renderer draws the screen; it never owns the sequence, the input type, or the order of the choices.

Field	What it carries
`node_id`	Stable identifier for this question or display screen
`kind`	`question` (captures an answer), `display` (an informational screen), or `consent` (a consent the patient accepts or declines; its wording, when served, rides `content`)
`section_id`	The section of the questionnaire this node belongs to
`control`	Which input to draw. The full list, with the answer each one sends, is in controls and their answers
`option_codes`	For choice controls: the stable codes of the selectable options, in served order
`options`	Optional per-option presentation hints — see below
`required`	Whether an answer is required to advance
`prefill`, `prefilled_value`	Prefill behavior for a value the platform already knows — see below
`may_auto_advance`	A hint that the renderer may advance immediately after a selection, without a separate continue button
`theme`	Your brand’s presentation overlay — theme tokens for your renderer to apply. See Brand configuration
`copy`	The question’s headline text, served from the reviewed question wording in the compiled questionnaire — not brand copy. A brand overlay can restyle a question but can never supply or override this wording. Absent is valid; render from the code when it is unset

A question node’s answer is shaped by its control: see controls and their answers for every control. Always send the served node_id with the answer. A display node carries no answer — send its node_id with no answer to move past it. It may reference the offerings it presents through offering_refs, and its values always come from the server — a display screen never asserts an outcome the platform has not produced.

Controls and their answers

Every question node names one control. These are all the values the server serves, and the answer each one takes in the answer object of POST /v1/instrument/next:

`control`	What to draw	The answer to send
`single_select_cards`	Choice cards	`{"codes": ["<option code>"]}`
`multi_select_cards`	Choice cards, several may be selected	`{"codes": ["<option code>", "..."]}`
`search_select`	A searchable list of options	`{"codes": ["<option code>", "..."]}`
`scale`	A scale	`{"value": 7}` (a number)
`number`	A number field	`{"value": 180}` (a number)
`number_pair`	Two number fields, such as a blood pressure reading	`{"pair": [120, 80]}` (exactly two numbers, in served order)
`date`	A date field	`{"value": "1990-04-21"}` (`YYYY-MM-DD`, a real calendar day)
`text`	A one-line text field	`{"value": "..."}` (a string)
`long_text`	A multi-line text field	`{"value": "..."}` (a string)
`phone`	A phone number field	`{"value": "+1 555 010 0199"}` (a string shaped as a US phone number)
`email`	An email field	`{"value": "[email protected]"}` (a string shaped as an email address)
`address`	An address field with as-you-type suggestions	`{"address": {"suggestion_id": "..."}}` or `{"address": {"manual": {...}}}`
`file_capture`	A file upload question (photo, video or document)	None from your storefront: it continues in the member portal (see below)

How the answers work:

Choice controls (single_select_cards, multi_select_cards, search_select) send stable option codes from option_codes, never display text. Whether one code or several may be sent comes from the question, not the control: a question that takes one answer refuses a second code, even on search_select. See option codes for the exclusive rule.
Number controls (scale, number) send a JSON number. A number sent as a string is refused. When the node carries a unit, show it beside the field.
number_pair sends pair, an array of exactly two numbers.
Text-shaped controls (date, text, long_text, phone, email) send a string. date, phone and email are checked for their shape: a date must be YYYY-MM-DD and a real day, a phone a ten-digit US number, and a value such as N/A is refused with an entry in issues. An answer of only spaces on a required question counts as no answer.
address sends either the suggestion_id of a suggestion from GET /v1/instrument/address/suggest or a manual address with line1, city, state, postal_code and country (and an optional line2). When the address’s state differs from the state the patient gave earlier, the step carries a flag. To go ahead despite the mismatch, include "override_state_mismatch": true in the address answer.
file_capture (a file upload question: photo, video or document) is never answered on your site. Your storefront’s intake does not ask the patient for it: the patient answers it in the member portal after they sign in, so their files never pass through your site or your server. When the questionnaire reaches such a question, the step marks it as continuing in the member portal and gives you the link to send the patient there. Send the patient to that link; there is no answer for your storefront to submit.

Two answers do not depend on the control:

A prefilled value you show for confirmation (prefill: confirm) is confirmed with {"confirmed": true}. See prefill.
A consent node is answered with {"consent": {"acknowledged": true}} to accept or {"consent": {"acknowledged": false}} to decline, with the node’s consent_version as version. Declining a treatment consent ends the questionnaire with status: blocked. A node that carries consent_kind: communications_consent (an email or text message opt-in) never blocks: accept and decline both move on.

A control your renderer does not recognize is a value missing from your renderer, not an answer you can skip: the server will not advance without a valid answer. Treat an unknown control as a fault to fix in your renderer.

Option codes and presentation hints

For choice controls, the answer you submit is always the stable option code, never display text. Codes survive rewording, so a copy change on a choice never breaks a stored answer or your integration. When the step carries an options array, it lists the same codes as option_codes, in the same order — served order is owned by the questionnaire and cannot be changed by theming — with per-option hints:

exclusive: true marks a “none of these”-class option that cannot be combined with any sibling. When the patient selects it, clear the other selections; when they select a sibling, clear the exclusive option. Resolve the conflict silently in the control — the latest selection wins — rather than showing an error message.
classification_code rides on a banded choice — for example a blood-pressure or frequency range — so a patient-friendly band carries its classification alongside the stable code.

{
  "session_id": "sess_a1b2c3",
  "journey_id": "jny_8kQ2mX",
  "status": "active",
  "node": {
    "node_id": "conditions_current",
    "kind": "question",
    "section_id": "medical_history",
    "control": "multi_select_cards",
    "required": true,
    "option_codes": ["cond_diabetes_t2", "cond_hypertension", "cond_none"],
    "options": [
      { "code": "cond_diabetes_t2" },
      { "code": "cond_hypertension" },
      { "code": "cond_none", "exclusive": true }
    ]
  }
}

The options array is optional: when it is absent, render from option_codes alone. The exclusive rule is enforced on the server either way — an answer that combines an exclusive code with another selection is rejected with 422 and the session does not advance — so a renderer without the hint still cannot submit a contradictory answer; it just learns about the conflict from the response instead of preventing it in the control.

One question per screen

Each step carries exactly one node — the wire itself enforces one question per screen. Use section_id if you want to show which part of the questionnaire the patient is in; use may_auto_advance to skip the continue button where the hint allows it. Behind that screen the questionnaire holds two kinds of content apart, as described in How it works: the marketing and qualification screens you shape, and the medical questionnaire the physician side governs. The separation is checked mechanically when the platform compiles a questionnaire — a question that captures a medical fact cannot sit in a qualification section, and a questionnaire that tries fails to compile. Your renderer never needs to tell them apart: every node arrives through the same loop, already in its governed place.

Prefill: ask once, confirm always

When the platform already holds a value for a question, the node’s prefill field says what to do:

suppress — the value is known and stable; the question is dropped from the flow entirely. A patient is never asked twice for something like a date of birth.
confirm — the value is shown in prefilled_value for explicit confirmation. The confirm step always renders; a prefilled value is never accepted on the patient’s behalf. This is also how a contact prefill from an entry link arrives — staged, unverified, and confirmed by the patient before anything is recorded.
collect — nothing is known; ask normally.

When an answer is rejected

Every answer is re-validated on the server, whatever the client already checked. A rejected answer returns 422 with the same question re-presented and the specific problems in issues; the session does not advance. Render the issues against the control and resubmit — the loop continues exactly as before.

Completion and the hand-off

Once every required answer is in, the response carries status: complete and a null node. If the session began from an entry link with a validated entry context, the step also carries handoff:

{
  "session_id": "sess_a1b2c3",
  "journey_id": "jny_8kQ2mX",
  "status": "complete",
  "node": null,
  "handoff": {
    "redirect": "https://storefront.example.com/thanks",
    "promo": "SPRING20",
    "test": true
  }
}

redirect is present only when it matched your brand’s redirect allowlist — anything else was dropped when the session started, so an unlisted URL can never surface here. promo is your opaque token, passed through unchanged. The hand-off never carries patient data.

Recording a drop-off

If the patient leaves without finishing, call POST /v1/instrument/abandon with the session_id. The drop-off is recorded against the session, and the response is the same step shape with status: abandoned. The way back in is a later resolve carrying the same journey_id in the X-Journey-Id header — a fresh session that applies everything the patient already answered.

​One loop, two calls

​The server is the sole authority

​One session, two identifiers

​Anatomy of a step

​The rendered question

​Controls and their answers

​Option codes and presentation hints

​One question per screen

​Prefill: ask once, confirm always

​When an answer is rejected

​Completion and the hand-off

​Recording a drop-off