What you’ll do
1
Create the patient
POST /v0.1/patients with a phone in E.164 — the response carries the patient id.2
Select the active questionnaire
GET /v0.1/questionnaires?status=active, then choose by status, never by list position.3
Submit the intake
POST /v0.1/questionnaire-responses with a subject and status: "completed". The platform
creates the encounter and returns its id.4
Take payment
POST /v0.1/checkouts/sessions with the price’s provider_price_id.5
Receive the outcome
Order status and tracking arrive as prescription webhook events at an endpoint you register
with OpenLoop (by arrangement) — see Order status and tracking. There is no order read.
The short answer on orders
You never create an order, and you cannot read one. A clinician reviews the intake and prescribes; the charting note that records the prescription is what triggers the medication order, and the platform then hands it to the pharmacy. So your integration takes payment and then listens. OpenLoop sends a signed prescription webhook event to an HTTPS endpoint you give your implementation contact (by arrangement — there is no self-serve registration):prescription.created, prescription.ordered, prescription.shipped
and prescription.cancelled. Each event carries the order’s data.status and
data.timestamps.*, plus data.carrier and data.tracking_ref once it ships.
There is no partner order read; order status and tracking arrive as these events. Payment state is
not on them — read it from the billing events or GET /v0.1/subscriptions / GET /v0.1/invoices
(see Payments and checkout). Order status and tracking and Prescription events have the event
attributes.
The short answer on encounters
You do not create the encounter, and you do not send us an encounter id. Submit the intake with asubject reference and status: "completed", and the platform creates the intake
encounter for you and returns its id on the response.
Two consequences worth internalising before you build:
encounter_idis a value you store, not a resource you read. The201from the submit andGET /v0.1/questionnaire-responses/{id}both carry it; encounters themselves are not readable on the partner surface. Store it beside the response id: it is the key that brings the clinician’s encounter note back to you, throughdata.encounter_idon theintake.*andcharting.*events and theencounter_idfilter onGET /v0.1/questionnaire-responses(staging only for now). See Encounter notes.- With several concurrent medications, each intake has its own response and its own
encounter_id. Keying your own records by questionnaire-response id is sufficient.
encounter_id is accepted on submit and honoured if you send it, in which case no encounter is
created for you. Use that only when attaching a response to an encounter you already
have. For the standard intake flow, omit it.
Encounters are not readable on the partner surface, and there is no create, update or delete. An encounter created by
a test submission stays in the tenant — keep test patients separate from real ones.
The first leg — patient, intake, payment
If you are staging your integration, this is the slice to build first. It stops at payment and needs nothing downstream of it.Sequence — the whole journey
Relational model
PRESCRIPTION_EVENT links to PATIENT through data.emr_patient_id, the patient’s /v0.1 id, when
the event carries it. An event without it has only the opaque data.patient_ref, and how that maps to
a /v0.1 patient is agreed per tenant when the webhook endpoint is registered.
Recipe 2.1 · Create the patient
phone must be E.164. A national format is rejected with a 400, so normalise before you send.
"phone": "(312) 555-0142" returns 400 with
phone: phone must be E.164 format.
Locked by check
phone-must-be-e164.Recipe 2.2 · Select the active questionnaire
Select bystatus, never by list position — the order is not a contract.
?status=active returns every active form, so narrow it as
Programs and identifiers describes, then hold the id in your own configuration.
Locked by check
select-active-questionnaire.Recipe 2.3 · Submit the intake and take payment
Submit with asubject and status: "completed", and the platform creates the intake encounter
and returns its id.
encounter_id with the response id.
Locked by check
intake-creates-encounter.type must match the price you are selling — subscription for a recurring
price — and items take the price’s provider_price_id:
Locked by check
checkout-session-succeeds-for-a-recurring-price.What comes back
The intake submission returns the response id and the encounter id together; the response read-back repeats both.Verifying a submission
The API is the system of record you verify against. A submission is proven by two checks, not by looking for the patient in the tools your care team uses:- The
201carrieddata.idanddata.encounter_id. GET /v0.1/questionnaire-responses/{id}returns the answers you sent and the sameencounter_id.
encounter_id is missing or step 2 is empty, the submission failed even though it returned
201 — re-read the validation warning on Questionnaire workflow. If both hold, it landed. The tools your care
team uses are fed from the platform on a per-tenant schedule and with a delay; whether a given
record type reaches them is a tenant configuration, not a signal about your call. Ask your OLH
implementation contact for your tenant’s sync statement before you test against those tools.
Locked by check
intake-creates-encounter.Gotchas
Response envelope varies by service — do not write one shared pagination helper. Clinical
resources (patients, questionnaires, questionnaire-responses, appointments)
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 (see API status, “Response envelopes differ by endpoint”). Always log request_id; it is how support finds
your call.And the envelope also differs between a list and a single read of the same resource.
GET /v0.1/patients returns { items, request_id }, each patient un-wrapped in items[];
GET /v0.1/patients/{id} returns { data: { … }, request_id }. Branch on which call you made,
not on the resource.status === "completed" and subject.type === "Patient" with
an id present.
- Submitting
status: "in-progress"creates the response but no encounter (noencounter_idcomes back). No error is returned. Submit partial intakes only if you intend this. - Omitting
subjectcreates an orphaned response with no patient linkage and no encounter. No error is returned. Some older integration examples omitsubject; do not follow them.
201 and a response id. The absence shows as a missing encounter_id.
Locked by check
in-progress-creates-no-encounter.Locked by check
missing-subject-creates-no-encounter.Related
Questionnaire workflow
Who defines the questions, and how to return answers keyed by
link_idPayments and checkout
The next leg: create a session with
provider_price_id for the treatmentNot eligible
When this stage goes wrong: the intake was submitted and no order followed

