request_id from the response before reporting anything.
Authentication and access
My token works but a specific endpoint returns403. 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 yourrequest_id.- An error mentioning the
Authorizationheader, a missingCredentialparameter, or an invalidkey=valuepair — 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/sessionsgives this error because/checkouts/sessionsisPOST-only. Others that look forbidden on aGET—reservations,invoices/previews— also work onPOST. 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 therequest_id; it does not block checkout.
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:
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 returns404.
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.
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/subscriptionsrequires?email=— and an email with no billing customer behind it is a404 Customer not found, not an empty list.
{ 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 a201, 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.
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; payload and staging-only status: 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:
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 GETs 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 onGET /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 asdata.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.
