> ## Documentation Index
> Fetch the complete documentation index at: https://openloop.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Questionnaire workflow — who defines what

> Who owns intake content: fetch the definition, render by link_id, and return answers — single, multi-select or free text — as given.

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

| | Owns |
| - | - |
| **OpenLoop** | The questions, their types, their `link_id` identifiers, and the clinical meaning behind them |
| **OpenLoop** | Authoring, versioning and activating each form, and retiring the old one |
| **You** | How the questions are presented — grouping, ordering, pagination, wording of your own labels, progress UI, validation UX |
| **You** | Returning the answers, keyed by the `link_id` OpenLoop gave you |

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_id`s.**

## 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.

## 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.

```json theme={null}
{
  "questionnaire_id": "<from GET /v0.1/questionnaires>",
  "subject": { "id": "<patient id>", "type": "Patient" },
  "status": "completed",
  "answers": {
    "q1": { "value_string": "210 lb" },
    "q2": { "value_boolean": true },
    "q3": { "value_date": "2026-01-15" }
  }
}
```

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`:

| Item `type` | Answer key |
| - | - |
| `string`, `text` | `value_string` |
| `boolean` | `value_boolean` |
| `date` | `value_date` |
| `integer` | `value_integer` |
| `decimal` | `value_decimal` |
| `choice`, `open-choice` | the option's own typed value as given — `value_coding` for a coded option, `value_string` for an uncoded one (or the shorthand `{"concept_id": <code>}`); `open-choice` free text as `value_string` |
| any item with `repeats: true` | an **array** of those answer objects — see *Multi-select* below |

> [!TIP]
>
> 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.

```bash curl theme={null}
curl -X POST https://api-staging.openloophealth.com/v0.1/questionnaire-responses \
  -H "authorization: Bearer $TOKEN" \
  -H 'content-type: application/json' \
  -d '{
    "questionnaire_id": "<questionnaire id>",
    "subject": { "id": "<patient id>", "type": "Patient" },
    "status": "completed",
    "answers": {
      "conditions": [
        { "value_coding": { "system": "https://openloop.health/concept-id", "code": "diabetes", "display": "Type 2 diabetes" } },
        { "value_coding": { "system": "https://openloop.health/concept-id", "code": "hypertension", "display": "High blood pressure" } }
      ]
    }
  }'
```

```json Response theme={null}
{ "data": { "id": "<response id>",
            "answers": { "conditions": [ { "value_coding": { ... } }, { "value_coding": { ... } } ] } },
  "request_id": "..." }
```

Read back, the answer is the same array in the same order. Three shapes, measured against staging
on 2026-09-11:

| What you send under the `link_id` | Result |
| - | - |
| An array of answer objects — `[{ "value_coding": {…} }, { "value_coding": {…} }]` | `201`, and the array is stored and read back as sent. **This is the multi-select form** |
| A single answer object — `{ "value_coding": {…} }` | `201`. One selection; valid on a repeating item too |
| An array nested under the typed key — `{ "value_coding": [{…}, {…}] }` | `400` — `answers.<link_id>: Invalid input`, `error_code: VALIDATION_ERROR` |

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.

> [!TIP]
>
> 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:

| Field | Meaning | You key on it for |
| - | - | - |
| `link_id` | **The identifier you must key your answer to.** Never invent or translate these | Every answer you return |
| `text` | The question as OpenLoop words it | Presenting the question |
| `type` | `string`, `text`, `boolean`, `date`, `integer`, `decimal`, `choice`, `open-choice`, `attachment`, … | Choosing the typed answer key |
| `required` | Whether the answer is expected | Your own validation, since the API does none |
| `repeats` | Whether the item may be answered more than once — **this is the multi-select flag** | Sending an array of answer objects, per *Multi-select* above |
| `read_only`, `max_length` | Presentation and validation hints | Your renderer |
| `answer_options[]` | The options for a `choice` or `open-choice` item, each carrying exactly one typed value | Rendering options and returning the value as given |
| `items` | Nested items — a group, so render its children together | Grouping |
| `concept_id` | OpenLoop's concept code for the question, when the item carries one | Coded answers and clinical review — optional everywhere, see below |
| `enable_when[]`, `enable_behavior` | The conditions under which the item is shown, and whether `all` or `any` must hold | Showing and hiding questions — see *Conditional questions* below |

`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*.

> [!TIP]
>
> 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.

```json theme={null}
{
  "link_id": "reactions",
  "text": "Did the medication cause any of the reactions below?",
  "type": "choice",
  "required": true,
  "enable_when": [
    { "question": "medication_tried", "operator": "=", "value_coding": { "system": "https://openloop.health/concept-id", "code": "1001" } }
  ],
  "enable_behavior": "any"
}
```

* `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

> [!WARNING]
>
> **This endpoint validates almost nothing, so a wrong mapping still returns `201`.** It does not
> check that your `link_id`s 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.

> [!TIP]
>
> Locked by check `unknown-link-id-is-not-validated`.

> [!NOTE]
>
> **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.

> [!TIP]
>
> Locked by check `uncoded-options-carry-value-string`.

> [!NOTE]
>
> **`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*.

> [!TIP]
>
> 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

## Related

> [card] [Integration flow](https://openloop.mintlify.site/cookbook/integration-flow.md)
>
> Where this sits in the journey, and the two ways an intake fails silently

> [card] [Programs and identifiers](https://openloop.mintlify.site/cookbook/programs-and-identifiers.md)
>
> How to find the right form for a program, and which id each endpoint wants

> [card] [Not eligible](https://openloop.mintlify.site/cookbook/not-eligible.md)
>
> When this stage goes wrong: the intake was accepted and no prescription followed


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.