What you’ll do
1
Send a key where the platform takes one
Two appointment writes require an
Idempotency-Key; nine billing writes accept one.2
Look before you create
GET /v0.1/patients?email=<address> is the de-duplication read — there is no upsert.3
Re-send only what is safe
Reads are safe. A create without a key is not, and a key already spent on a finished attempt
replays that attempt instead of making a new one.
4
Report a duplicate you already made
Two patients, two ids, one email — keep one, and ask OpenLoop to remove the other. You cannot
delete it yourself.
Which calls are safe to send again
Recipe · Send an Idempotency-Key where the platform takes one
Idempotency-Key is a request header, and the published reference declares it on twelve
write operations. On two of them it is required:
Omitting the header on either appointment write is rejected before any body or id validation —
a
PATCH at an id that does not exist still answers the key, not a 404:
Locked by check
idempotency-key-required-on-appointment-writes.The key is not the same shape everywhere
The reference asks for a different kind of value per family, and the difference matters:- Appointments — a fresh UUID per action. The key is global to your integration, not scoped to an endpoint or an appointment, so a key already spent on a booking will replay that booking if you send it on a later cancel or reschedule. Failures are stored too: change the request or search for a new slot, and you need a new key.
POST /v0.1/subscriptions— a deterministic, order-scoped value such asinitial-subscription:{provider_customer_id}:{order_id}, so that re-sending the same attempt de-duplicates: a client that mints a fresh random value on retry creates a second subscription. But the key is per attempt, not per order. Reusing it after the attempt has reached a terminal outcome replays the stored response instead of doing the work again — a retry after a400decline returns that same400, even when the patient has supplied a replacement card, and anitemsarray changed under an unchanged key is rejected as an idempotency conflict rather than retried. Mint a new key for a genuinely new purchase attempt. The replay window (roughly 24 hours) also outlives the subscription’s ownincomplete_expireddeadline (roughly 20 hours), so a key can still be replaying a decline long after the attempt it belongs to has expired. Payment failure documents that400(a declined off-session charge onPOST /v0.1/subscriptions) and what it leaves behind.POST /v0.1/checkouts/sessions— an opaque random value such as a UUID.
x-idempotency-replayed: true and the original body, and the
stored response lives for roughly 24 hours.
The header semantics above — the replay window,
x-idempotency-replayed, the per-family key advice,
and the replay of a stored 400 decline — are the published reference’s own description of these
parameters, read 2026-09-11. The checks on this page exercise the absence of a key, which is
what the harness can send; they do not measure replay behaviour.Recipe · De-duplicate a patient before you create one
There is no upsert and no key onPOST /v0.1/patients, so the read is the de-duplication step:
items array means you already created this patient — take items[0].id rather than
posting again.
Percent-encode the address. A raw + in the query string arrives as a space and the filter
rejects it:
Locked by check
dedup-by-email-before-create.Recipe · What a repeated create actually does
Sending the samePOST /v0.1/patients twice returns 201 twice, with two different ids. The
email filter then returns both records. Nothing rejects the duplicate — de-duplication is yours.
id before you send the create,
and reconcile it against the email read when a request times out. There is no partner delete
to undo the duplicate. Keep using the id you mapped, and ask your OLH implementation contact to remove the
other — say whether intake was submitted against it, because a completed submit has already created
an encounter. See User migration. The same holds for a duplicated /questionnaire-responses
create: correct an in-progress response with PUT /v0.1/questionnaire-responses/{id} (published)
rather than posting again, and ask OpenLoop to remove a duplicate.
Locked by check
repeat-create-makes-a-second-patient.Recipe · Read after a write
The read after a write can be stale. Immediately after a patient write answered200,
GET /v0.1/patients/{id} was observed still returning the previous state, and the new state a
moment later (verified on staging 2026-09-11; the write observed was a patient delete, which is no
longer partner-callable, and the lag has not been re-measured on PUT). Read-back is eventually
consistent, so a read that still shows the old state is not proof your write was lost. Wait and
read again before you re-send anything.
Recipe · Why a repeated subscription update adds a line item
PUT /v0.1/subscriptions/{provider_subscription_id} takes no Idempotency-Key, and its items
array is addressed by id:
An upgrade written as
items: [{ provider_price_id: "price_…" }] therefore adds a line every time
it is sent. Retry it after a timeout and the subscriber ends up paying for two of the same thing.
After a timeout on a plan change:
GET /v0.1/subscriptions/{provider_subscription_id}and compareitemsagainst what you meant to send.- If the change did land, stop — the response to a
PUTis the subscription, not the payment result, so also readstatusand/invoices?status=openper Upsell and cross-sell. - If you must re-send, address the existing item by
provider_item_idrather than adding a price.
The
items semantics above are the published request schema for this route, read 2026-09-11, not
something the checks on this page measured — exercising it needs a paid subscription in your tenant.What comes back
Gotchas
The clinical writes take no idempotency key at all.
POST /v0.1/patients,
/questionnaire-responses and /reservations declare no such header in the published reference,
so the platform has nothing to de-duplicate on. Guard these client-side.Every response carries
request_id, success or failure. Log it on the first attempt as well as the
retry — it is what an escalation is keyed on. See Errors for the envelope.Related
Integration flow
The happy path these retries interrupt: create the patient, submit intake, pay
Appointments and scheduling
The two writes that require an
Idempotency-Key before they will run at allUpsell and cross-sell
The subscription update whose retry adds a line item
Payment failure
What a
400 decline on POST /v0.1/subscriptions leaves behind, and why retrying it under the old key replays itErrors
The error envelope,
request_id, and what each status means
