What you’ll do
1
Fetch the definition
GET /v0.1/questionnaires?status=active, and store every link_id it gives you.2
Render it your way
Group, order, paginate and label the items however suits your funnel.
3
Return the answers
POST /v0.1/questionnaire-responses with answers as an object keyed by link_id.4
Validate on your side
The endpoint checks almost nothing, so validate required items and value types before you send.
The division
You do not author the clinical content, and you do not need to. You do own the entire patient
experience around it.
OpenLoop authors and activates your forms; you read them
Questionnaire authoring is not part of the partner surface; the two questionnaire calls you make areGET /v0.1/questionnaires and GET /v0.1/questionnaires/{id} (published). To add a form, change a
question or retire one, ask your OLH implementation contact; OpenLoop authors it and activates it,
and it appears in GET /v0.1/questionnaires?status=active once it is active. Everything else on
this page — reading the definition, applying enable_when, keying answers by link_id, and
submitting with POST /v0.1/questionnaire-responses (or updating an in-progress response with
PUT /v0.1/questionnaire-responses/{id}) — stays yours.
Why it works this way
Thelink_id on each item is the stable identifier that ties an answer to its clinical meaning
downstream — review, prescribing, and any automation configured for the program. If you invented
your own field names and mapped them at the boundary, that mapping becomes a second source of
truth, and a silent mis-map produces clinically wrong data with a 201.
So: fetch the definition, render it however you like, return answers under the original
link_ids.
What you may change, and what you may not
Yours to decide: which items appear on which screen, the order within a screen, whether you show one question at a time or twenty, your own supporting copy, client-side validation, whether a question is hidden based on an earlier answer, and how you label things for your brand. Not yours to change: thelink_id of any answer you return, the type you answer with, or the
clinical wording where you present OpenLoop’s question rather than your own framing.
Recipe 2.4 · Return the answers keyed by link_id
answers is an object keyed by link_id — not an array. This is the single most
common mistake on this endpoint.
answers as an array and the call is rejected with 400 and Expected object.
Each answer object carries exactly one typed key. Match it to the item’s type:
Locked by check
answers-keyed-by-link-id-are-accepted.Multi-select — an item whose definition says repeats: true
repeats: true is the multi-select flag. Send an array of answer objects under the item’s
link_id; each element is an ordinary answer object carrying exactly one typed key.
That last row is the one place this endpoint does validate: the shape of an answer value is
checked even though the
link_id and the answer type are not. There is no third form — repeated
JSON keys are not an option — so if you are not sending an array, you are not sending a
multi-select answer.
Locked by check
repeats-true-takes-an-array-of-answer-objects.What comes back
GET /v0.1/questionnaires?status=active returns the definitions. Each carries items[], and each
item carries:
concept_id, enable_when and enable_behavior are in the published QuestionnaireItem schema
as of 2026-09-19; types generated from an older copy of the document will not carry them. Read
concept_id defensively either way — it is optional everywhere, see Assumptions, checked.
Locked by check
definition-carries-link-ids-and-types.Conditional questions (enable_when)
A form’s branching is part of the definition, and applying it is your renderer’s job. An item that
carries enable_when is shown only when its conditions hold against the patient’s current answers;
the platform does not apply the conditions for you, on render or on submit.
questionis thelink_idof the controlling item.operatoris one ofexists,=,!=,>,<,>=,<=. Exactly onevalue_*key is present —value_boolean,value_coding,value_string,value_integer,value_decimalorvalue_date— and forexistsit isvalue_boolean.- Compare a
value_codingcondition to the answer’s coding bysystemandcode(or byconcept_idwhere both carry one); compare the others by typed value. enable_behaviorsays whetherallconditions oranyone of them must hold. It is present whenever there is more than one condition; treat a single condition asall.- A hidden item is not rendered and not answered: omit it from the submission.
requireddoes not apply while the item is hidden. Evaluate top-down on every change, because a controlling answer can hide a whole branch. - Not every form branches. Items without
enable_whenare always shown.
enable_when, its six value_* keys and enable_behavior are in the published
QuestionnaireItem and QuestionnaireEnableWhen schemas (published). No check exercises them now:
the conformance check that authored a form with conditions and read them back used the authoring
call, which is OpenLoop’s. When OpenLoop authors a form, the platform rejects a condition whose
question is not a link_id on the same form (verified on staging 2026-10-02), so a condition you read always points at an item on the same
definition.
Gotchas
Locked by check
unknown-link-id-is-not-validated.Choice options are in the definition, and each option carries exactly one typed value. Every
choice and open-choice item carries answer_options[]. A coded option carries a
value_coding (system, code, display). An uncoded option carries a value_string
instead, and no coding at all: on one staging weight-management form a referral-source item offers {"value_string": "Social media"}, {"value_string": "Friend or family"} and
{"value_string": "My doctor"}. The published QuestionnaireAnswerOption schema declares
value_coding, value_string, value_date, value_integer, value_reference, value_time and
initial_selected and requires none of them, so this is contractual rather than a quirk of one
form. Branch on which key the option actually has; a renderer written to assume value_coding
silently drops every uncoded option. Return the option’s value exactly as you received it — never
the display text, which is accepted and stored uninterpreted. Options are clinical content:
re-fetch the definition on a schedule and re-render from it.Locked by check
uncoded-options-carry-value-string.concept_id is optional everywhere — never require it. Options coded in OpenLoop’s own system
(https://openloop.health/concept-id) carry a concept_id that repeats the code, with the code
a string and the concept_id the same value as an integer ("216" and 216 on one staging
form’s first coded option, locked by the check below) — so compare them as strings if you compare them at all.
Options borrowed from an external system — the state pickers use USPS codes — carry none, so key
on the option’s typed value rather than on concept_id. Answerable non-choice items may carry
a concept_id of their own, and some active forms omit it entirely: a generic seed form left
active in a tenant can sit first in GET /v0.1/questionnaires?status=active with items that
return exactly link_id, text and type. choice, display and group items carry none.
concept_id is declared in the published QuestionnaireItem and QuestionnaireAnswerOption
schemas but not required, so generated types mark it optional — see Assumptions, checked.Locked by check
choice-items-carry-options-and-concept-ids.201 today. Apply enable_when and required on your side.
Submitted, but not visible to your care team yet. The read-back is the proof — see Verifying a
submission on Integration flow. Care-team tools follow on a per-tenant sync schedule, with a
delay, and may not be connected on staging.
Nothing labels a questionnaire with its program. A questionnaire has no program field, and the
list endpoint cannot filter by one. You cannot ask “which form is the intake for this program”. Hold the
questionnaire id per program in your own configuration — see Programs and identifiers.
Before you build
- Fetch the definition and store it, including every
link_id - Build your renderer against
link_id, never against question text or position - Validate required items and value types on your side, because the API will not
- Get the per-program questionnaire ids in writing and hold them in configuration — options come with the definition
- Re-fetch definitions periodically — the questions can change, and your
link_idmap must follow - Apply
enable_whenin your renderer and omit hidden items from the submission — the API will not do either for you - Route every new form, wording change or retirement through your OLH implementation contact — OpenLoop authors and activates forms; there is no partner call that does it
Related
Integration flow
Where this sits in the journey, and the two ways an intake fails silently
Programs and identifiers
How to find the right form for a program, and which id each endpoint wants
Not eligible
When this stage goes wrong: the intake was accepted and no prescription followed

