Skip to main content
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:
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. 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. 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:
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 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 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.