Skip to main content
If you are migrating from a system where you owned the form definitions, this is the page that matters most. The division of responsibility here is different, and building on the old assumption is expensive to unwind.

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 are GET /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

The link_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: the link_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. answers is an object keyed by link_id — not an array. This is the single most common mistake on this endpoint.
Send 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.
Read back, the answer is the same array in the same order. Three shapes, measured against staging on 2026-09-11: 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.
  • question is the link_id of the controlling item. operator is one of exists, =, !=, >, <, >=, <=. Exactly one value_* key is present — value_boolean, value_coding, value_string, value_integer, value_decimal or value_date — and for exists it is value_boolean.
  • Compare a value_coding condition to the answer’s coding by system and code (or by concept_id where both carry one); compare the others by typed value.
  • enable_behavior says whether all conditions or any one of them must hold. It is present whenever there is more than one condition; treat a single condition as all.
  • A hidden item is not rendered and not answered: omit it from the submission. required does 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_when are 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

This endpoint validates almost nothing, so a wrong mapping still returns 201. It does not check that your link_ids exist on the questionnaire, that required items are answered, or that the value type matches the item type. A 201 means “accepted”, not “correct”. Validate against the definition you fetched, on your side, before you send.
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.
The API carries the conditions but does not apply them. A submission that answers a hidden item, or omits a required one, still returns 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

  1. Fetch the definition and store it, including every link_id
  2. Build your renderer against link_id, never against question text or position
  3. Validate required items and value types on your side, because the API will not
  4. Get the per-program questionnaire ids in writing and hold them in configuration — options come with the definition
  5. Re-fetch definitions periodically — the questions can change, and your link_id map must follow
  6. Apply enable_when in your renderer and omit hidden items from the submission — the API will not do either for you
  7. 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

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