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

# Start here

> Start here: the seven build stages in order, the five calls that prove your tenant is provisioned, and what to read before writing code.

This cookbook is staged. You do not need most of it on day one — build intake first, get it
working end to end, then come back for the next leg.

## If you are an AI coding agent

Build in the stage order below. Every recipe names the exact `/v0.1` path, the request body and the response shape, and the check that keeps it true. Key answers by `link_id`, return option codings as given, use `provider_price_id` at checkout, and treat a `201` as "accepted", not "correct". Read *Known gaps and staging* before deciding an empty collection is a bug. Order status is not a read: it arrives as prescription webhook events at an endpoint you register with OpenLoop (by arrangement), so do not build an order-polling loop. Recipe headings are numbered by stage on the seven stage pages (`## Recipe 3.2 · …`, where 3 is the stage) and unnumbered on the six *When things go wrong* pages (`## Recipe · …`), because a failure recipe belongs to a situation rather than to a stage.

## What you'll do

Build the stages in this order. Each is independently useful, and each assumes the one before it
works.

> [card] [1 · Start here](https://openloop.mintlify.site/cookbook/getting-started.md)
>
> Authenticate, reach the API, and confirm your tenant is provisioned

> [card] [2 · Intake](https://openloop.mintlify.site/cookbook/integration-flow.md)
>
> Create a patient, administer the right form, and submit it

> [card] [3 · Payment](https://openloop.mintlify.site/cookbook/payments-and-checkout.md)
>
> Take payment for a treatment. The order itself follows the clinician's prescription

> [card] [4 · Status and tracking](https://openloop.mintlify.site/cookbook/order-status-and-tracking.md)
>
> Status and tracking: prescription webhook events (by arrangement), and the clinician's encounter note read by the encounter id your submit returned

> [card] [5 · Scheduling](https://openloop.mintlify.site/cookbook/appointments-and-scheduling.md)
>
> Offer availability and book visits

> [card] [6 · Refills](https://openloop.mintlify.site/cookbook/refills.md)
>
> Let a patient reapply, and track the resulting prescription

> [card] [7 · Growth](https://openloop.mintlify.site/cookbook/upsell-and-cross-sell.md)
>
> Sell add-ons, upgrade a subscription, and run retention

> [card] [Lab ordering](https://openloop.mintlify.site/cookbook/lab-ordering.md)
>
> By arrangement, outside the stages: order lab tests for a patient you have already created

> [card] [When things go wrong](https://openloop.mintlify.site/cookbook/errors.md)
>
> Six pages that interrupt the stages above: payment failure, not eligible, cancel/pause/refund,
> order exceptions, retries and idempotency, and the error envelope itself

| Stage | Read | You will be able to |
| - | - | - |
| **1 · Start here** | Start here · Getting started | Authenticate, reach the API, and confirm your tenant is provisioned |
| **2 · Intake** | Integration flow · Questionnaire workflow · Programs and identifiers | Create a patient, administer the right form, and submit it — the platform creates the clinical encounter |
| **3 · Payment** | Payments and checkout | Take payment for a treatment. The order itself follows the clinician's prescription |
| **4 · Status and tracking** | Order status and tracking · Prescription events · Encounter notes | Status and tracking: prescription webhook events (by arrangement). OpenLoop sends each order milestone, with tracking, to an HTTPS endpoint you register with your implementation contact; there is no order read. The clinician's encounter note comes back as a questionnaire response on the intake's encounter: the `intake.*` and `charting.*` events carry the `encounter_id`, and the questionnaire-response list filters by it |
| **5 · Scheduling** | Appointments and scheduling | Offer availability and book visits |
| **6 · Refills** | Refills | Let a patient reapply, and track the resulting prescription |
| **7 · Growth** | Upsell and cross-sell | Sell add-ons, upgrade a subscription, and run retention |

## Recipe 1.1 · Day one

**Read three pages, in this order:**

1. **Getting started** — hosts, credentials, the token exchange, and the response conventions every
   call shares
2. **Integration flow** — the whole journey as a sequence diagram, plus the first-leg slice if you
   are staging your build
3. **Questionnaire workflow** — who defines the questions and who controls presentation. Read this
   before you design any intake UI

**Then run these five calls and confirm each one:**

| # | Call | Confirms |
| - | - | - |
| 1 | `POST /v0.1/auth/token` | Your credentials work and you can read `data.access_token` |
| 2 | `GET /v0.1/patients` | Your token is accepted on a resource endpoint |
| 3 | `GET /v0.1/questionnaires?status=active` | An intake form exists for you |
| 4 | `GET /v0.1/products?active=true` | You have something sellable |
| 5 | `GET /v0.1/configs` | Your payment configuration is in place |

**If 3, 4 or 5 comes back empty, stop.** That is not a fault in your code — your environment is
not seeded yet. Raise it before writing anything, because everything downstream depends on it.
*Known gaps and staging* explains what to ask for.

> [!TIP]
>
> Locked by check `day-one-five-calls`.

## What comes back

Four envelopes carry every answer in this cookbook. Learn these once and every page reads the same
way.

| Field | Meaning | You key on it for |
| - | - | - |
| `data.access_token` | The bearer token from `POST /v0.1/auth/token` | Every subsequent call's `authorization` header |
| `items[]` | A collection read. Clinical resources page with an `after` cursor; the product catalogue carries a `pagination` object, but catalogue paging is not implemented yet, so do not build a cursor loop on it (see *API status*, "Response envelopes differ by endpoint") | Listing, paging, and telling "none yet" from "not seeded" |
| `data` | A single read or a write — the resource itself, wrapped. `GET /v0.1/patients/{id}` and `POST /v0.1/questionnaire-responses` both return `data` | Reading one record, and reading back what you just created |
| `request_id` | Present on every response, success or failure | Support. Log it on every call, including the ones that worked |
| `error.error_code` | On a failure, the machine-readable cause — `VALIDATION_ERROR`, `NOT_FOUND` | Branching on a failure instead of matching on message text |

## Reference, when you need it

| Page | Use it when |
| - | - |
| **API status** | You want to know whether an endpoint behaves as the reference describes, before you build on it |
| **Assumptions, checked** | You are about to build on an assumption and want it confirmed or corrected first |
| **FAQ and troubleshooting** | You have an error in front of you and want to know what it means |
| **Known gaps and staging** | Something is missing or empty and you need to know whether it is you, your environment, or us |
| **User migration** | You are bringing existing patients across. Read the caveat first — this is not yet a defined path |

## Gotchas

Four things worth knowing before you start.

**The partner surface is `/v0.1`**, including authentication at `/v0.1/auth/token`. Other version
prefixes are not for partners.

**Collections return `items`; writes return `data`.** Two different envelopes, and pagination
differs by resource; the product catalogue does not page yet. *Getting started* has the detail.

> [!WARNING]
>
> **A `200` does not always mean your request was understood.** Some endpoints ignore a query
> parameter they do not recognise and return the full collection. Check that a filtered result looks
> filtered.

> [!NOTE]
>
> **Log `request_id` on every call.** It is on every response, success or failure, and it is the
> fastest way for us to find your exact request.

## What this cookbook is

Each page states what we have verified and what we have not. Where the published API reference and
this cookbook disagree, tell us — we would rather fix it than have you work around it.

Where a page says to ask your OLH implementation contact, that is a real handoff, not a deflection:
some things are provisioned per customer and cannot be self-served yet. Those are called out
explicitly rather than left for you to discover.

## Related

> [card] [Getting started](https://openloop.mintlify.site/cookbook/getting-started.md)
>
> Hosts, credentials, the token exchange, and the response conventions every call shares

> [card] [Integration flow](https://openloop.mintlify.site/cookbook/integration-flow.md)
>
> The whole journey as a sequence diagram, plus the first-leg slice to build first

> [card] [When things go wrong](https://openloop.mintlify.site/cookbook/errors.md)
>
> The six failure pages, starting with the error envelope every endpoint shares


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