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

# FAQ and troubleshooting

> Errors and surprises integrators hit first — auth, empty collections, validation, hosts — with the cause and the fix for each.

Every entry below is a problem seen in a real integration or reproduced against the live API.
Always capture `request_id` from the response before reporting anything.

## Authentication and access

**My token works but a specific endpoint returns `403`. Is my credential missing a scope?**
Read the error body before assuming so. Three different failures all surface as `403`:

* `insufficient_permissions` — a genuine scope gap. Report it with your `request_id`.
* An error mentioning the **`Authorization` header**, a missing `Credential` parameter, or an
  invalid `key=value` pair — **this is almost always the wrong HTTP method for that path**, not a
  permission problem. Check the reference for the verb that path accepts and retry. Worked
  example: `GET /v0.1/checkouts/sessions` gives this error because `/checkouts/sessions` is `POST`-only. Others that look forbidden on a
  `GET` — `reservations`, `invoices/previews` — also work on `POST`. Only
  conclude an endpoint is unavailable to you after trying the documented method.
* An error naming a **payment-provider permission** such as `payment_method_configurations_read` — a
  configuration gap on the OpenLoop side. Report it with the `request_id`; it does not block checkout.

**Auth fails only for some of my developers.**
Very likely the WAF. Requests from some non-US regions are filtered at the edge and present as an
auth failure, not a geo block. Send your OLH implementation contact the blocked request and its source
region for a one-time allow-list. Developers on a non-US VPN hit the same thing.

**How long do tokens last?**
The token response carries `expires_in`; read it rather than hard-coding. Refresh via the
refresh-token endpoint in the standard OAuth pattern. Production access tokens are short-lived —
assume minutes, not hours — so build refresh in from the start rather than retrofitting it.

**Where do I send requests?**
Staging integration work goes to `api-staging.openloophealth.com`. The published reference
declares only the production host; a staging credential presented to production is rejected at the
gateway with a misleading error.

**I'm testing staging — should `audience` be the staging host too?**
No. **`audience` and the request host are two unrelated things, and confusing them is the most
common setup mistake.** `audience` is fixed at `https://api.openloophealth.com` for every
environment — staging and production both — because it identifies which API you're authorizing
against, not which server receives the call. The **host** is what changes: send the token request
and every API call to `api-staging.openloophealth.com/v0.1` for staging. Your production host is
confirmed by your OLH implementation contact at go-live — see *Getting started*. So a staging token
request looks like:

```
POST https://api-staging.openloophealth.com/v0.1/auth/token
{ "grant_type": "client_credentials", "client_id": "...", "client_secret": "...",
  "audience": "https://api.openloophealth.com" }
```

Setting `audience` to the staging host, or sending requests to the production host with a staging
credential, both fail — the first at token issuance, the second at the gateway with a misleading
error. **Staging and production also use different credentials** — a client id/secret pair from
one environment will not authenticate against the other.

## Paths and versions

**A documented endpoint returns `404`.**
A `404` and an empty list are different problems, and this entry is only about the `404`. Check the
prefix first: everything partner-facing is under **`/v0.1`**, including `/v0.1/auth/token`. If a
`/v1` path appears anywhere in your material it is a mistake — those routes are internal, and they
do not fail loudly. Then check the id: a `404` whose body carries `error.error_code: "NOT_FOUND"`
is about the id you passed, not about your access. See
[Tell a real 404 from a foreign one](https://openloop.mintlify.site/cookbook/errors.md#recipe-tell-a-real-404-from-a-foreign-one).

**A list I expect data in comes back empty.**
That is a different question, and usually a seeding one: an empty `items` array is a `200`, so
nothing was rejected. Confirm the filter value you interpolated was well formed — several
collections accept any string and return an empty page for a value that could never match — and
then see *Known gaps and staging*, which says what to ask for. Some collections require a filter
before they will answer at all:

* `GET /v0.1/subscriptions` requires `?email=` — and an email with no billing customer behind it is
  a `404 Customer not found`, not an empty list.

**My pagination works on patients but not on products.**
Clinical resources return `{ items, request_id }` with an
`after` cursor when there is a next page; the product catalogue returns
`{ items, pagination, request_id }`, but catalogue paging is not implemented yet, so do not build a
cursor loop on it. Do not write one shared pagination helper for the whole API. See
*API status*, "Response envelopes differ by endpoint", for what to do if products seem to be missing.

**A list endpoint returns `400`.**
Some collections require a filter: `/v0.1/subscriptions` and `/v0.1/invoices` need `email`. The `400` body names the missing parameter.

## Intake and encounters

**I submitted an intake and got a `201`, but no `encounter_id` came back.**
An intake encounter is created only when **both** conditions hold: `status` is `"completed"`, and
`subject` is present with `type: "Patient"` and an id. Miss either and you get a `201` with a
response id and silently no encounter — the missing `data.encounter_id` is the only sign. Submitting `status: "in-progress"` does this deliberately.

**I sent an `encounter_id` and no encounter was created.**
That is correct behaviour. A supplied `encounter_id` is honoured and suppresses automatic
creation. Omit it for standard intake.

**Can I read the encounter, or link it back to the intake?**
You cannot read the encounter itself; encounters are not a readable resource on the partner surface.
You can use its id. The completed submit returns `encounter_id` (verified on staging 2026-10-05),
`GET /v0.1/questionnaire-responses/{id}` repeats it, and
`GET /v0.1/questionnaire-responses?encounter_id=<id>` lists every response on that encounter: your
intake and, once a clinician charts it, the encounter note (verified on staging 2026-10-19; the
filter is staging only for now, not yet in the production release). The `intake.*` and
`charting.*` events carry the same id as `data.encounter_id`. Store it beside the
response id. Each intake produces its own response and its own `encounter_id`, even with several
concurrent medications. See [Encounter notes](https://openloop.mintlify.site/cookbook/encounter-notes.md).

**I received `charting.completed`. How do I read the note?**
By encounter. The event carries `data.encounter_id`, the same id your intake submit returned, and
no answers. `GET /v0.1/questionnaire-responses?encounter_id=<data.encounter_id>&status=completed`
returns the note beside your intake (the encounter filter was verified on staging 2026-10-19). Take
the row whose `questionnaire_canonical` ends in `/<questionnaire_ref>`; it has no
`questionnaire_id`. Read on `charting.completed` only: `charting.created` and `charting.signed`
arrive while the form is still `in_progress`. When `data.encounter_id` is `null`, the form was
started outside the charting workflow and the event does not let you find it. Walkthrough with samples:
[Encounter notes](https://openloop.mintlify.site/cookbook/encounter-notes.md); payload and staging-only status: [Charting](https://openloop.mintlify.site/events.md#charting).

**Can I create or edit a questionnaire?**
No. Questionnaires are authored by OpenLoop; you read them with
`GET /v0.1/questionnaires` and `GET /v0.1/questionnaires/{id}`; send content changes to your OLH
implementation contact. See *Questionnaire workflow*.

**I submitted an intake, but the tools my care team uses do not show it. Did it fail?**
Not if it reads back. The `201` carrying `data.encounter_id` and
`GET /v0.1/questionnaire-responses/{id}` returning your answers are the proof — see *Verifying a
submission* on *Integration flow*. Care-team tools are fed from the platform on a per-tenant schedule and with a delay, and on
staging they may not be connected at all. If the read-back is empty, that is the failure; if it is
not, ask your OLH implementation contact for your tenant's sync statement.

**My patient record has no date of birth or phone number.**
The field names are `birth_date` and `phone`. Misnamed fields such as `date_of_birth` or
`phone_number` are discarded without a validation error, so the record persists without them. The
damage is only visible on read-back.

## Request-shape errors on writes

**`phone: phone must be E.164 format (e.g. +14155552671)`**
`POST /v0.1/patients` requires E.164. `(312) 555-0142` is rejected; `+13125550142` is accepted.

**`answers: Expected object, received array`**
On `POST /v0.1/questionnaire-responses`, `answers` is an **object keyed by `link_id`**, not an
array:

```json theme={null}
{ "answers": { "q1": { "value_string": "210 lb" } } }
```

The value object carries exactly one typed key — `value_string`, `value_boolean`, `value_integer`,
`value_decimal`, and so on. The published reference documents this correctly; the array form is
simply a natural mistake if you are used to answers as a list.

**`customer_data.name is required when provider_customer_id is not provided`**
On a checkout session, `customer_data` needs **both** `email` and `name` unless you pass an
existing `provider_customer_id`.

**`each item requires provider_price_id`**
Checkout items take `provider_price_id`, not `price_id`. See *Payments and checkout*.

**`Failed to create Stripe checkout session: No such price: '<id>'`**
The platform accepted your request and the payment provider rejected the price. Almost always this
means you used a price from an **archived** product: those ids belong to a previous payment
account. Re-run with `GET /v0.1/products?active=true` and take `provider_price_id` from
`GET /v0.1/products/{product_id}/prices`. Checkout itself works — this is a stale catalogue entry, not an outage.

**Writes and reads use different envelopes.**
`POST` responses wrap the resource in `data`; list `GET`s wrap collections in `items`. So a create
returns `{ data: {...}, request_id }` while a list returns `{ items: [...], request_id }`.

## Orders and status

**Is there a dashboard where I can verify payments and submissions?**
No. The API and the webhook events are the verification surface. A landed payment shows as a paid
invoice on `GET /v0.1/invoices?email=<billing email>&status=paid`; a landed intake shows on its
read-back; an order shows only through the prescription webhook events (by arrangement). Log the
`request_id` of every call — it is your support handle.

**How do I read order status?**
You do not read it; you receive it. There is no partner order read. Order status arrives as signed
prescription webhook events at an HTTPS endpoint you give your OLH implementation contact. Four verbs
are delivered: `prescription.created`, `prescription.ordered`, `prescription.shipped` and
`prescription.cancelled`. Read the stage from `data.status` and the accumulating `data.timestamps.*`;
once it ships, `data.tracking_ref` and `data.carrier` carry tracking. Payment state is not on these
events — read it from the billing events or `GET /v0.1/subscriptions` / `GET /v0.1/invoices`. See
*Order status and tracking* and *Events*.

**Should I poll, or subscribe to webhooks?**
Webhooks — there is nothing to poll. Registration is not self-serve: give OpenLoop your endpoint, and
confirm delivery mechanics (signature, retries) with your implementation contact when it is
registered. Key each event to your patient on `data.emr_patient_id`, the patient's `/v0.1` id, when
the event carries it; it is omitted when the id isn't known, never `null`. `data.patient_ref` is an
opaque reference that is not guaranteed to be the `/v0.1` patient id, so how your tenant correlates an
event without `emr_patient_id` is agreed at registration.

**An order has not moved for days. How do I detect that?**
Age the latest event you received for the order (keyed by `data.resource_id`) against its `occurredAt`
and `data.status`. An order still at `created` or `ordered` past your threshold has stalled — it was
never sent to the pharmacy, or never shipped. Escalate with the `data.resource_id` and the envelope
`id` of the last event.

## Environment and data

**Staging returns empty collections for my program.**
Seeded data is minimal and is not seeded per program by default. If your protocols are not
present, nothing relevant to you exists yet — ask your OLH implementation contact to seed your
questionnaires and product catalogue. This is the single most common reason a new integration
stalls in its first week.

**How do I delete test patients or test intakes?**
You cannot. Partners do not delete patients, questionnaire responses, consents or document references. Use clearly synthetic test
data, keep it separate from real patients, and ask your OLH implementation contact to clean up
staging.

**My test patients are invisible to the API.**
Credentials are bound to a specific payment account. A mismatch between the account your sandbox
is attached to and the one your credentials belong to makes your own test data unreachable.
Confirm the account id and key in writing for staging and production separately.

**Which enumerated values can I depend on?**
Clinical resources use fixed value sets that the platform does not extend.
Order status is platform-specific and lives on the prescription webhook events as `data.status`
(`created`, `ordered`, `shipped`, `delivered`, `cancelled`, `unknown`), documented on *Prescription
events* rather than the OpenAPI reference. Generate types from the published reference for everything
else rather than transcribing values.


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