> ## 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. # How questions work > The model behind the question endpoints: facts, controls, screening versus medical questions, and the engine that serves an intake one question at a time. 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](/api-reference/offering-configuration/list-the-facts-a-qualification-question-may-bind). 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](/api-reference/offering-configuration/create-a-new-screening-fact-for-your-brand), 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: | You'll see | It means | | -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | *"…must bind a fact from the catalog"* | The `fact` field is missing or doesn't resolve. Pick a fact from the catalog — or, if you need a new one, register it first through the minted-facts endpoint, then bind it. | | *"…asks for medical information"* | The fact you picked is medically classified. This question belongs to the clinical intake, which clinicians govern — it can't be a screening question. | | A duplicate **warning** (not an error) | Your question overlaps one the medical intake already asks. You can keep it — the patient still answers only once — but consider whether you need it at all. Warnings never block saving. | ## Publishing — when patients see your changes [Creating](/api-reference/offering-configuration/create-a-qualification-library-question) and [editing](/api-reference/offering-configuration/edit-a-qualification-library-question) library questions changes your library only. [Attaching questions to an offering](/api-reference/offering-configuration/add-a-library-question-to-an-offering), [editing an offering's copies](/api-reference/offering-configuration/edit-an-offerings-qualification-question), and [reordering](/api-reference/offering-configuration/reorder-an-offerings-qualification-questions) take effect through the offering's [published question set](/api-reference/offering-configuration/publish-an-offerings-qualification-questions) — the [read endpoint for an offering's qualification](/api-reference/offering-configuration/read-an-offerings-composed-qualification-questions) 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** * [List the facts a question may bind](/api-reference/offering-configuration/list-the-facts-a-qualification-question-may-bind) — `GET /v1/account/question-library/facts` * [Register a new screening fact](/api-reference/offering-configuration/create-a-new-screening-fact-for-your-brand) — `POST /v1/account/question-library/minted-facts` * [List your library](/api-reference/offering-configuration/list-your-brands-qualification-question-library) — `GET /v1/account/question-library/questions` * [Create a library question](/api-reference/offering-configuration/create-a-qualification-library-question) — `POST /v1/account/question-library/questions` * [Edit a library question](/api-reference/offering-configuration/edit-a-qualification-library-question) — `PATCH /v1/account/question-library/questions/{question_id}` * [Delete a library question](/api-reference/offering-configuration/delete-a-qualification-library-question) — `DELETE /v1/account/question-library/questions/{question_id}` **An offering's qualification** * [Read the composed questions](/api-reference/offering-configuration/read-an-offerings-composed-qualification-questions) — `GET /v1/account/offerings/{offering_ref}/qualification` * [Add a library question](/api-reference/offering-configuration/add-a-library-question-to-an-offering) — `POST /v1/account/offerings/{offering_ref}/qualification` * [Edit an offering's copy](/api-reference/offering-configuration/edit-an-offerings-qualification-question) — `PATCH /v1/account/offerings/{offering_ref}/qualification/questions/{question_id}` * [Remove a question](/api-reference/offering-configuration/remove-an-offerings-qualification-question) — `DELETE /v1/account/offerings/{offering_ref}/qualification/questions/{question_id}` * [Reorder the questions](/api-reference/offering-configuration/reorder-an-offerings-qualification-questions) — `PUT /v1/account/offerings/{offering_ref}/qualification/order` * [Publish the questions](/api-reference/offering-configuration/publish-an-offerings-qualification-questions) — `POST /v1/account/offerings/{offering_ref}/qualification/publish`