Skip to main content
Your patients’ intake is built from questions — some you write, some written by medical professionals — served one at a time by an engine that decides what to ask, what to skip, and what never to ask twice. This guide explains the model behind the question endpoints so the fields you’ll use (fact, control, options, copy) make sense.

​
The one-minute model

  • A question collects a fact. A fact is a single piece of information with a stable code — residence_state, glp1_current_use, date_of_birth. The question is the asking; the fact is the answer’s identity.
  • An intake is an ordered plan of questions. When a patient starts, the platform assembles one plan: your brand’s screening questions and the shared medical questions, in order.
  • An engine serves the plan one question at a time. It checks each question before showing it: some questions carry a condition (“only ask this if…”), and any fact the patient has already provided is never asked again.

​
Facts and the catalog — why you must pick one

Every question binds a fact from the platform’s fact catalog. This is required, and it’s what makes two things work:
  1. Patients answer each thing once. If your screening question collects residence_state, and the medical intake also needs the patient’s state, the patient won’t be asked twice — their earlier answer carries forward automatically. This only works because both questions name the same fact.
  2. Answers mean something. A fact has a type (a choice, a date, a number…) and, for choice facts, a fixed set of option codes. Your display wording is fully yours; the underlying codes stay stable, so the answer is usable no matter how you phrase the question.
Browse the catalog through the fact-catalog endpoint. If the information you want to collect is genuinely new, first register it as a new screening fact for your brand through the minted-facts endpoint, then bind that fact when you create the question — it joins the same catalog so the answer-once behavior still applies.

​
Therapies and modes — the two context values, spelled out

The fact-catalog endpoint takes a therapy and a mode, and these are the only two places you ever name a context yourself — everywhere else the platform derives the context from the offering. The values are a fixed vocabulary, not free text:
  • therapy — the treatment area you’re authoring for. The current vocabulary has exactly one value: weight_loss. New therapies join this list when their shared medical intake ships; the API reference’s enum for the parameter is always the authoritative list.
  • mode — initial (the first-visit intake) or refill (the refill flow). Today only initial is served.
An unknown therapy or an unserved mode answers a 404 — nothing is guessed. Creating, editing, attaching, and reordering questions never take a therapy or mode: your brand comes from your API key, and each offering already implies its own context.

​
Controls — how the patient answers

The control field picks the input the patient sees: choice cards (single or multi select), a scale, a number, a date, free text, an address, a file capture, and so on. Controls affect presentation only — the fact defines what’s collected; the control defines how it feels to answer.

​
Your questions and medical questions — two layers, one intake

  • Screening questions (yours). Coarse, non-medical questions at the front of the funnel — where the patient lives, what they’re looking for. You create them in your question library, attach them to your offerings, reorder them, and word them however fits your brand.
  • Medical questions (shared). The clinical intake — health history, medications, safety screens — is written and governed by medical professionals and is identical for every brand offering a given treatment. It cannot be added to, removed from, reworded, or reordered by any brand. This is a structural guarantee, not a policy: the platform rejects any attempt at save time.
The line between the two is enforced when you create a question: a screening question that asks for medical information is rejected with a plain-language message telling you why. Medical information belongs in the medical intake, where clinicians govern it.

​
Conditional questions — how the engine decides what to serve

Some questions carry a condition: only ask this if an earlier answer calls for it. For example, the medical intake asks about current GLP-1 dose only if the patient said they currently or recently use a GLP-1 medication — a patient who answers “never” simply never sees the dose questions. How it works, precisely:
  • Conditions are evaluated on the server, between questions. A skipped question is never sent to the browser at all.
  • A condition can only reference facts collected earlier in the plan — the engine never has to wait for an answer that hasn’t happened yet.
  • When in doubt, the engine asks. If a condition can’t be evaluated — the referenced answer is missing, or the rule isn’t recognized — the question is served rather than hidden. For medical questions, the safe failure is always asking.
Today, conditions appear on medical questions. Authoring conditions on your own screening questions is coming to this API; when it arrives, your conditions will be able to reference your own earlier screening answers, and the same engine will serve them.

​
When a question you created “doesn’t appear”

Usually this is the engine working as designed, not a fault. Check, in order: the patient may have already provided that fact elsewhere (answer-once — it won’t be re-asked) · a condition on the question may have evaluated false for this patient · the question may be attached to a different offering than the one this patient is on.

​
What the errors mean

Creating or editing a question can be rejected. The three you’ll meet:

​
Publishing — when patients see your changes

Creating and editing library questions changes your library only. Attaching questions to an offering, editing an offering’s copies, and reordering take effect through the offering’s published question set — the read endpoint for an offering’s qualification always shows you exactly what a patient will meet. Edits to an offering’s copy of a question never affect your library original or any other offering.

​
The endpoints

Every authoring operation described above, on the public reference. Your question library An offering’s qualification