Skip to main content
Read this before you build anything program-specific. The naming is documented; the identifiers are where integrations go wrong, and the reference does not warn you.

What you’ll do

1

Survey the catalogue

GET /v0.1/products?limit=100 — collect the distinct program_code values and their ULID program_ids.
2

Confirm each program is launchable

An active product with at least one provider_price_id.
3

Store the questionnaire id per program

Nothing in the API maps a form to a program, so the mapping lives in your configuration.
A program_id is read, never typed. It is a ULID you copy off an existing product in your catalogue; there is no program endpoint to look one up and nothing validates one you invent. Read the table in Recipe 2.5 before writing any call that carries it.

Recipe 2.5 · Resolve the identifiers each endpoint wants

Every program-specific identifier you send comes from a read you do first. The catalogue is the only namespace you work in: A product carries both the human label and the identifier: program_code is the short code your programs are known by, program_id is the ULID the platform keys on. Group by the code, identify by the ULID.
Locked by check program-id-comes-from-products.
There is no program endpoint: GET /v0.1/programs is not partner-reachable and returns a 403 naming the Authorization header, so a program_code → program_id lookup has to come from the catalogue read above. Nothing validates a program_id you send — the failure is a 404 or a silent mismatch later, not a 400 at build time.
Locked by check no-program-endpoint-for-partners.

The names the platform uses

Program codes are platform vocabulary, fixed when your programs are set up, and they are not always the words your team uses for the same program. Nothing in this cookbook lists them: the codes that apply to you are the distinct program_code values in your own catalogue, and the readiness report your OLH implementation contact posts names each of your programs with its code. If a search of your catalogue for the name you use returns nothing, search for the code.

Recipe 2.6 · Resolve a program’s questionnaire id once

OpenLoop authors and activates your forms; you read them. A program’s intake appears in GET /v0.1/questionnaires?status=active once OpenLoop has activated it — there is no partner call that creates or edits a form. ?status=active returns every active form in your tenant, including any left over from setup, so it does not identify a single form. ?title= narrows it — and this is a bootstrap step you run once, not a runtime lookup.
On the tenants we verified, ?title=<PROGRAM> returned exactly one match per program code. It is still not a stable contract — titles are editable and carry no format guarantee — so resolve the id once, store (program, questionnaire_id) in your own configuration, and never send a title from your application at runtime. Confirm the exact titles and ids with your OLH implementation contact before relying on them in production.
Locked by check title-filter-resolves-one-form.

Recipe 2.7 · Verify what your tenant has, per program

Nothing in this cookbook tells you which programs, forms, products or prices exist for you — they are seeded per tenant, and they change. Verify them yourself, in this order, and repeat the run whenever your OLH implementation contact tells you something was seeded: Every call is a read you can run today with your sandbox credential. Compare the three results per program and record the ids you will hold in configuration: the questionnaire id, the product id and its provider_price_id. The same three reads are what the readiness report your implementation contact posts is built from, so if the report and your run disagree, send both with the request_ids. Pharmacy readiness is the one thing you cannot read. Whether a program’s medications are set up to dispense is confirmed by OpenLoop in the readiness report; there is no partner call that answers it. An intake, an active product and a price make a program sellable; the readiness report is what makes it fillable. Do not launch a program the report has not cleared.
Locked by check tenant-seeding-is-readable-per-program.

What comes back

Gotchas

program_code is unvalidated free text with no enum. Tenants in staging carry a code and its lowercase twin as distinct codes with different program_id values, and stray test codes exist. Do not case-fold to match, and do not assume a code you see is intentional — compare with the codes in your readiness report.
Check the program_id you read. The catalogue is seeded by OpenLoop and the partner surface has no product write (no create, delete or archive), so a wrong program_id on a product is a seeding fault, not something you can fix or undo. A genuine program_id is a ULID: 26 characters, Crockford base32, no I, L, O or U. A real staging tenant carries a product with 01ZZZZZZZZZZZZZZZZZZZZZZZZ; if a value looks invented, it is, and it fails at order time rather than at read time. Report it to your implementation contact before building on it.
Locked by check product-program-filter-is-silently-ignored.
A partner does not create programs, products or prices. The commerce catalogue is seeded by OpenLoop per tenant; you read it (GET /v0.1/products, GET /v0.1/products/{product_id}, GET /v0.1/products/{product_id}/prices) and key checkout on provider_price_id. Ask your OLH implementation contact for a new program or catalogue entry, then read its ids off the catalogue.
Questionnaires cannot be program-scoped. A questionnaire carries id, url, version, name, title, status, experimental, publisher, description, purpose, date and items. There is no program field, and GET /v0.1/questionnaires filters only on status, title, cursor and limit — anything else returns 400. Forms are authored by OpenLoop, so there is no partner write that could attach a program either. So there is no API-level way to ask “which form is the intake for this program”. Get the questionnaire ids per program from your OLH implementation contact, or resolve them once as in Recipe 2.6, and hold them in your own configuration. Do not match on title at runtime — resolve it once, then read the id from configuration.
Locked by check questionnaires-cannot-be-program-scoped.
Nothing carries a program label anywhere else either. POST /v0.1/questionnaire-responses rejects program_code (400 Unrecognized key(s) in object). Forms are authored by OpenLoop, and the encounter a completed submit creates is not partner-readable — you get its encounter_id back, and it carries no program. So you cannot attach a program to a form, a response, or an encounter — the mapping has to live in your own configuration.
A program appearing in your catalogue does not make it launchable. Use ?limit=100, not ?active=true, when surveying — an archived product still tells you a program exists. But a program is only launchable when it has an active product with a price: GET /v0.1/products?limit=100 shows which programs exist at all, GET /v0.1/products?active=true which are sellable, and GET /v0.1/products/{product_id}/prices must return at least one provider_price_id. A program whose only product is archived, or whose product has an empty prices collection, cannot be sold. Both cases occur in staging.
Which programs are yours, whether each has its intake form and its catalogue seeded, and whether its pharmacy side is ready, is in the readiness report your OLH implementation contact posts in your shared channel. Intake and catalogue are tracked separately because they are seeded separately: you can build and test the intake flow for a program whose products are not yet in the catalogue, but checkout for it fails until they are. Pharmacy readiness is tracked there too, and only there — it is not readable through the API.
Before you build anything program-specific, in this order:
  1. GET /v0.1/products?limit=100 — collect distinct program_code values. These are the programs that exist for you
  2. Record the program_code → ULID program_id pairs, and sanity-check the ULIDs look real
  3. Confirm each program you intend to launch has an active product with a price. If not, stop and request it
  4. Resolve the questionnaire id for each program once, get it confirmed in writing, and store it in configuration
  5. Check the readiness report has cleared the program’s pharmacy side. If it has not, you can build and test intake, but do not launch

Questionnaire workflow

What a questionnaire definition carries, and how to answer it

Payments and checkout

The next leg: turn a catalogue price into a checkout session

Errors

When this goes wrong: the opaque 404 a wrong id produces, and how to read it