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

# Assumptions, checked

> Assumptions integrators arrive with, each confirmed or corrected against the live API, so you do not build on the wrong one.

Written for teams validating their design before building. Each row states an assumption we have seen partners make, and the verdict after testing it
against the live API.

## Intake and encounters

| Assumption | Verdict |
| - | - |
| "We create the encounter, then post the intake with its id." | **Corrected.** The platform creates the intake encounter when you submit a completed response with a `subject`. Omit `encounter_id`. |
| "We must never send `encounter_id`." | **Over-stated.** It is accepted and honoured; sending it suppresses automatic creation. Omit it for standard intake; send it only to attach a response to an encounter you already hold. |
| "The encounter references the intake that produced it." | **Holds, through the response, not the encounter.** Encounters are not readable, but `GET /v0.1/questionnaire-responses?encounter_id=<id>` returns the intake that created the encounter and any encounter note charted against it (verified on staging 2026-10-19). The `intake.*` and `charting.*` events carry the same id. |
| "We read the encounter back to confirm the intake landed." | **Not available.** A `201` carrying `data.encounter_id`, and `GET /v0.1/questionnaire-responses/{id}` returning the same id, are the proof (verified on staging 2026-10-05). |
| "A partial (`in-progress`) intake still produces an encounter." | **No.** Only `status: "completed"` does, and no error is raised otherwise. |
| "`subject` is optional — some examples omit it." | **It is effectively required.** Omitting it yields an orphaned response, no patient linkage, no encounter, and a `201`. |
| "Take `questionnaires[0]` from the list." | **No.** Select the questionnaire whose `status` is `"active"`. Lists can contain retired versions that still accept submissions. |
| "Any version prefix works." | **No.** The partner surface is `/v0.1` throughout, including `/v0.1/auth/token`. The `/v1` prefix is not the partner surface, and it does not fail loudly. The token exchange sent under `/v1` answered `200` with a working token and the identical `{data, request_id}` envelope — no signal at all. The active-questionnaire list sent under `/v1` answered `200` with an **empty** set and a different envelope (`items` plus `pagination`) where `/v0.1` returned five forms. An empty set reads as "this tenant has no data", which is far more dangerous than unrelated data or an error. Both observed on staging, 2026-09-11. |

## Patient records

| Assumption | Verdict |
| - | - |
| "Fields are `date_of_birth` and `phone_number`." | **Corrected.** They are `birth_date` and `phone`. Misnamed fields are discarded silently — the record persists without them. |

## Post-payment

| Assumption | Verdict |
| - | - |
| "We subscribe to webhooks to learn order status." | **Yes, by arrangement — and it is the only way.** Give your OLH implementation contact the HTTPS endpoint; there is no self-serve registration. Delivery mechanics (signature, retries) are confirmed with your implementation contact when the endpoint is registered. See *Order status and tracking*. |
| "We poll for order status." | **Not available.** There is no partner order read; order status and tracking arrive as prescription webhook events. |
| "Tracking numbers require a data export." | **No.** `data.tracking_ref` (with `data.carrier` for the carrier name) is on the prescription webhook events once the order ships (by arrangement). |
| "An event's `data.patient_ref` is our `/v0.1` patient id." | **No.** It is an opaque reference — not guaranteed to be your `/v0.1` patient id — and the event carries no email. Key on `data.emr_patient_id` instead when the event carries it: it is your `/v0.1` patient id, the `id` that `GET /v0.1/patients/{id}` takes, and it is omitted when the id isn't known, never `null`. How a tenant whose patients exist only through `POST /v0.1/patients` correlates an event without it is not specified yet; agree it when the endpoint is registered. |
| "We delete test patients when we are done." | **Not available.** Partners do not delete patients, questionnaire responses, consents or document references. Staging test data is cleaned up by OpenLoop. |
| "We integrate Stripe directly for payment." | **No.** Use the platform's payment endpoints (`/checkouts/sessions`, `/intents/*`) so clinical and billing records stay joined. |

## Enumerations and their authority

A fair concern when migrating from a system with overlapping, non-hierarchical enumerations: which
value sets can you depend on?

**Most status enumerations here are fixed value sets, and the platform does not extend them.**
Across the enumerated fields in the published contract, the clinical resources use these values
exactly:

| Resource | `status` values |
| - | - |
| QuestionnaireResponse | `in-progress` `completed` `amended` `entered-in-error` `stopped` |
| Questionnaire | `draft` `active` `retired` `unknown` |
| MedicationStatement | `active` `completed` `entered-in-error` `intended` `not-taken` `on-hold` `stopped` `unknown` |
| Observation | `registered` `preliminary` `final` `amended` `corrected` `cancelled` `entered-in-error` `unknown` |
| Consent | `draft` `proposed` `active` `inactive` `rejected` `entered-in-error` |
| DocumentReference | `current` `superseded` `entered-in-error` |

**Order status is the platform's own value set, carried on the prescription webhook events** (by
arrangement), not on an API resource. These values are published in the prescription webhook
contract — see *Events* and *Prescription events*:

| Event attribute | Values | Authority |
| - | - | - |
| envelope `type` | `prescription.created` `prescription.ordered` `prescription.shipped` `prescription.cancelled` | Published prescription webhook contract — see *Events* |
| `data.status` | `created` `ordered` `shipped` `delivered` `cancelled` `unknown` | Published prescription webhook contract — see *Events* |

These values are not in the OpenAPI document, so the type-generation advice below does not cover
them; take them from the prescription webhook contract (*Events*, *Prescription events*) and treat
an unknown value as a signal to check with your implementation contact.

> [!NOTE]
>
> For any enumerated field, the published OpenAPI document is authoritative and machine-readable.
> Generate your types from it rather than transcribing values; that way a value added upstream
> surfaces as a type error rather than a runtime surprise.
>
> **One field to keep treating as optional: `concept_id`.** Until 2026-09-19 the published
> `QuestionnaireItem` and `QuestionnaireAnswerOption` schemas did not declare `concept_id`, although
> live staging returned it on items and answer options; the schemas now declare it, together with
> `enable_when` and `enable_behavior` on items. Types generated from an older copy of the document
> will not carry them, so regenerate. `concept_id` stays optional wherever it appears — some items and
> some options never carry one — and *Questionnaire workflow* tells you how to read it.


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