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.
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.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 distinctprogram_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 inGET /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.
?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
Locked by check
product-program-filter-is-silently-ignored.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:
GET /v0.1/products?limit=100— collect distinctprogram_codevalues. These are the programs that exist for you- Record the
program_code→ ULIDprogram_idpairs, and sanity-check the ULIDs look real - Confirm each program you intend to launch has an active product with a price. If not, stop and request it
- Resolve the questionnaire id for each program once, get it confirmed in writing, and store it in configuration
- 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
Related
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
