Skip to main content
This API lets you build a patient storefront: run a patient through an intake questionnaire, and follow their enrollment through to fulfillment. It is a REST API over HTTPS with JSON request and response bodies, versioned under the /v1 path prefix. All examples on this site run against a test-mode environment with test-scoped keys and synthetic data only — see Environments. Every example calls the API base $PURPLE_API_BASE, an origin of the form https://api.<env>.purplelabelmd.com (the test environment’s hosts are on Environments), with /v1 written into every path, and authenticates with your test API key, $PURPLE_API_KEY. Both come with your welcome kit.

​
How a request is authorized

Your server presents a per-client API key as a bearer token, and most endpoints also take a brand header:
The key resolves to exactly one client (your tenant); the brand must belong to that client. Two exceptions are worth knowing before you read further. The three sign-in endpoints under /v1/auth/ are browser redirects on the API host and take no key. They are not your patients’ sign-in link: patients sign in on your member portal (see How a patient signs in). And a second, browser-safe credential exists for the two brand reads a public storefront page makes. Both are covered in Authentication.

​
How a patient signs in

Patients sign in on your brand’s member portal, not through the API. Link every “Sign in” or “My account” control to the member portal’s own sign-in route, on the member portal address in your welcome kit:
The patient must have a member portal session before they pay. The order belongs to the account that is logged in to the portal at payment, and only that account’s portal shows it.
Do not use the API’s /v1/auth/login as your patients’ sign-in link. It signs the patient in on the API host, with a different sign-in application, and does not give them a member portal session. See Login URLs and domains.

​
The endpoints, grouped

The API reference tab groups every endpoint by area:
  • Sessions & authentication — begin a sign-in on the API host, complete it, and log out (/v1/auth/login, /v1/auth/callback, /v1/auth/logout). This is not the patient sign-in link; see How a patient signs in.
  • Intake — start an intake session and walk it question by question (/v1/instrument/resolve, /v1/instrument/next, /v1/instrument/abandon). The server owns the question sequence, branching, and completion — a client can never skip or reorder questions.
  • Addresses — as-you-type address suggestions for the intake flow (/v1/instrument/address/suggest).
  • Enrollment — read the public status of a patient’s enrollment (/v1/journeys/{journey_id}/status).
  • Onboarding — the two brand reads a storefront makes before it renders a price (/v1/account/brands/{brand_id}/storefront, /v1/account/brands/{brand_id}/readiness).
  • Payments — start a checkout session, read an order’s payment status, and list your orders (/v1/payments/checkout-sessions, /v1/payments/{order_ref}/status, /v1/account/orders).
  • Brand configuration — your brand’s display identity, custom domains, and the browser origins your storefront may read from (/v1/account/brands/{brand_id}/config, /v1/account/brands/{brand_id}/domains, and the browser-origin allowlist).
  • Offering configuration — list and enable offerings, set their price and display copy, and author the qualification questions attached to them (/v1/account/brands/{brand_id}/offerings, /v1/account/brands/{brand_id}/pricing, /v1/account/question-library/...).
  • Webhooks — subscribe to platform events and manage delivery endpoints (/v1/webhooks/event-types, /v1/webhooks/registrations, and /v1/webhooks/registrations/{registration_id}/test).

​
Conventions

  • IDs are opaque and prefixed — for example jny_ for an enrollment, whr_ for a webhook registration. Treat them as strings.
  • Errors use RFC 7807 application/problem+json bodies.
  • No patient data leaves through status reads — the enrollment status read returns identifiers and status values only.
Ready to make your first call? Start with the Quickstart.