> ## Documentation Index
> Fetch the complete documentation index at: https://openloop.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Programs and identifiers

> How a program is identified in the catalogue, how to verify which programs, forms, products and prices your tenant has, and how to hold the ids.

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_id`s.

**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.

> [!WARNING]
>
> **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:

| Endpoint | Wants | Read it from |
| - | - | - |
| `GET /v0.1/products/{product_id}/prices` | `product_id` | `GET /v0.1/products` — `items[].id`; the product's `program_id` (a **ULID**, 26 characters, e.g. `01ARZ3NDEKTSV4RRFFQ69G5FAV`) groups products of one program |
| `POST /v0.1/checkouts/sessions` | `provider_price_id` | `GET /v0.1/products/{product_id}/prices` |
| `POST /v0.1/questionnaire-responses` | `questionnaire_id` | `GET /v0.1/questionnaires`, resolved once — Recipe 2.6 |

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.**

```bash curl theme={null}
# catalogue: program_code + ULID program_id + provider prices
curl "https://api-staging.openloophealth.com/v0.1/products?limit=100" \
  -H "authorization: Bearer $TOKEN"
```

```json Response theme={null}
// GET /v0.1/products?limit=100
{ "items": [ { "id": "...", "program_id": "01ARZ3NDEKTSV4RRFFQ69G5FAV", "program_code": "<PROGRAM>",
               "active": true, "current_price_id": "..." } ],
  "pagination": { ... }, "request_id": "..." }
```

> [!TIP]
>
> 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.

> [!TIP]
>
> 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.

```bash curl theme={null}
curl "https://api-staging.openloophealth.com/v0.1/questionnaires?title=<PROGRAM>" \
  -H "authorization: Bearer $TOKEN"
# once per program code
```

```json Response theme={null}
{ "items": [ { "id": "<questionnaire id>", "title": "<PROGRAM> Intake (Initial)", "status": "active",
               "items": [ ... ] } ],
  "request_id": "..." }
```

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.

> [!TIP]
>
> 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:

| # | Call | You are checking | Missing means |
| - | - | - | - |
| 1 | `GET /v0.1/questionnaires?status=active`, then `?title=<PROGRAM>` | Exactly one active intake per program | Intake cannot be built for that program |
| 2 | `GET /v0.1/products?active=true` | The distinct `program_code` values with an active product — these are the programs you can sell today | The program is not set up, or not sellable, for you yet |
| 3 | `GET /v0.1/products/{product_id}/prices` | Each active product has at least one `provider_price_id` | Checkout cannot start for that program |

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_id`s.

**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.

> [!TIP]
>
> Locked by check `tenant-seeding-is-readable-per-program`.

## What comes back

| Field | Meaning | You key on it for |
| - | - | - |
| `items[].program_id` (products) | The **ULID** program id of the commerce catalogue, assigned when OpenLoop seeds the product | Grouping products of one program; never sent on a partner write (the catalogue has no partner write) |
| `items[].program_code` (products) | Free-text program label, unvalidated and with no enum | Grouping your own catalogue — never as an identifier |
| `items[].id` (products) | The product id | `GET /v0.1/products/{product_id}/prices` |
| `items[].provider_price_id` (prices) | The price you sell | `POST /v0.1/checkouts/sessions` |
| `items[].id` (questionnaires) | The questionnaire id you store per program | Every intake and refill submission |
| `after` (questionnaires) / `pagination` (products) | Clinical resources page with an `after` cursor; the product catalogue carries `pagination`, but catalogue paging is not implemented yet (see *API status*, "Response envelopes differ by endpoint") | Paging clinical resources; products do not page yet |
| `request_id` | Present on every response, success or failure | Support, when you report a problem |

## Gotchas

> [!WARNING]
>
> **`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.

> [!WARNING]
>
> **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.

> [!TIP]
>
> Locked by check `product-program-filter-is-silently-ignored`.

> [!WARNING]
>
> **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.

> [!WARNING]
>
> **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.

> [!TIP]
>
> Locked by check `questionnaires-cannot-be-program-scoped`.

> [!NOTE]
>
> **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.

> [!NOTE]
>
> **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.

> [!NOTE]
>
> **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.

> [!NOTE]
>
> **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

## Related

> [card] [Questionnaire workflow](https://openloop.mintlify.site/cookbook/questionnaire-workflow.md)
>
> What a questionnaire definition carries, and how to answer it

> [card] [Payments and checkout](https://openloop.mintlify.site/cookbook/payments-and-checkout.md)
>
> The next leg: turn a catalogue price into a checkout session

> [card] [Errors](https://openloop.mintlify.site/cookbook/errors.md)
>
> When this goes wrong: the opaque `404` a wrong id produces, and how to read it


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.