Skip to main content
When your integration is provisioned, your onboarding contact hands you a welcome pack. This page lists exactly what is in it, what comes with it, and the two secrets you hold. The other integration pages use the same names.

​
Your API base, stated once

Every endpoint on this site is called on one origin. The pack names it PURPLE_API_BASE:
Use the value your pack states: it is the base of the environment your key was issued for, and your key works only there. Before go-live that is the test environment, whose hosts are listed on Environments. The base is an origin only. The /v1 prefix is written into every path on this site, so a full request URL is always $PURPLE_API_BASE/v1/.... Never add /v1 to the base itself. The API reference is written the same way: its server is the origin, the test environment’s API base, and every path in it starts with /v1. The production base is a later, separately-gated hand-off at go-live. Every curl example on this site uses two environment variables: $PURPLE_API_BASE and $PURPLE_API_KEY.

​
What the welcome pack contains

For each of your brands, the pack shows:
  • The brand: its name and its brand id (brd_...). The brand id rides every request in the X-Brand-Id header. One client can hold several brands, and each call names exactly one.
  • Site settings: a paste-ready block of environment variables. There is no payment-provider key in the block, and you do not need one. The hosted checkout runs on the payment provider’s own key (see the checkout door).
  • Member portal address: the hostname of your brand’s member portal, for example member.example.com. It is where your patients sign in, check out, see their orders and complete the identity step. Until the address is set up the pack reads “Not recorded”, and no checkout can run. Ask your onboarding contact before you build against it.
  • Sign-in link: the member portal’s own sign-in route on that address.
    Link every “Sign in” or “My account” control to this URL. It signs the patient in to the member portal. Do not use the API’s /v1/auth/login for this (see Login URLs and domains). If your brand also has an active custom sign-in domain, the pack shows that host as well.
  • Offerings: each offering enabled for your brand, as its offering reference (offering_ref, the readable code such as SEMA-1M) and its offering id (sku_id, shaped sku_...), in columns headed “Offering reference” and “Offering id”. For example: A checkout-first link also carries the offering’s therapy (for this example, weight_loss). You do not compose it: the pack issues each offering’s exact checkout link (next item). Where a call asks for the offering code, as the price write’s sku field does, send the offering_ref (SEMA-1M), never the sku_id. See Identifiers and error types for which call takes which id.
  • Entry mode and checkout link: one row per enabled offering, with:
    • its entry mode, Questions-first or Checkout-first. The mode decides how your storefront starts a patient (see which way in);
    • which setting decided it: “Set for this offering”, “The account’s setting”, or “No mode set, so the platform default”;
    • the exact checkout link to build. A checkout-first link carries offering_ref, sku_id and therapy. A questions-first link carries offering_ref and journey_id only. Your storefront does not open a questions-first link itself: it hands the patient to the checkout door with a form POST, and the door sends the patient to this link with their journey_id filled in. Take the offering_ref for that form from the link. See handing the patient to checkout.
    Where a row shows no link, it says why. Ask your onboarding contact to resolve it before you build against that offering. Your server can read the same facts, and keep them current as offerings are added, with GET /v1/account/brands/{brand_id}/offerings: each offering’s offering_ref, sku_id, therapy, entry mode and checkout link, with its price and readiness.
  • Starter merchandising step: the call that adopts the starter product copy for the brand, POST /v1/account/brands/{brand_id}/starter-merchandising with pack_version 3 (see before a price is payable).
  • Consent and identity held by the platform: Yes / No: whether the platform holds your patients’ consent and identity records for this brand. The pack reads “Can’t tell yet” when it could not check. Whether your checkout consent documents are configured is a separate question, answered by GET /v1/account/brands/{brand_id}/readiness. Payment stays locked until those documents are configured.

​
Your own steps before patients arrive

Three settings are yours to make with your own key, in one call, PUT /v1/account/brands/{brand_id}/config:
  1. Your display name (display.display_name), with your logo and theme if you want them. It is always required: patients see it on every platform page.
  2. Who holds your consent documents (consent_holder). There is no default: until it is chosen, your brand is not ready for patients. See who holds your consent documents.
  3. Your legal document links, when you hold your consent documents (consent_holder client): your terms of service, privacy policy and telehealth informed consent (legal_documents.terms, legal_documents.privacy and legal_documents.telehealth), each an absolute https URL. Set every one your questionnaires link to. When the platform holds them, you skip this step: the platform’s own documents apply by default. Until the platform’s legal pages are published, patients see a “not available” notice in place of those links.
To check what is still missing, read the patient_readiness report beside data on your configuration readback, or on an intake resolve (GET /v1/instrument/resolve): it lists each missing item and how to set it. See is your brand ready for patients?.

​
What comes with the pack

Your onboarding contact also gives you:
  • Your API key value, once (see below).
  • Your publishable brand key, if you asked for browser reads. It is optional; see your credentials.
  • An onboarding id (onb_...): the reference for your onboarding. Quote it when you ask your onboarding contact where things stand, or read your progress yourself with your API key. See the Onboarding timeline.
You can read your brand configuration back yourself at any time with GET /v1/account/brands/{brand_id}/config. Your offerings are not part of that configuration: list them with GET /v1/account/brands/{brand_id}/offerings.
Use only invented test patients whose names include the uppercase word TEST; test mode never charges a real card.

​
The two secrets you hold

Two of the values you hold are secrets. Each is shown to you exactly once and then held only by you. The platform never shows either again.
  • Your API key (PURPLE_API_KEY) is issued by your onboarding team when your account is set up. There is no self-serve key generation. You receive it once, at issue: store it in your secret manager right away. Treat it as server-side only, and never put it in browser code or a public repository. To replace one, ask your onboarding contact to rotate it.
  • Your webhook signing secret is the one you create yourself: it is generated when you call POST /v1/webhooks/registrations and returned exactly once in that response. The platform holds it after that and never returns it again. Store it the moment you receive it: it is what you verify delivery signatures with. If you lose it, register a new endpoint to mint a fresh one.
Keeping the secrets on your side is the point: no one, including us, can read your signing secret back out, so a delivery you accept is a delivery only you could have verified. For how each secret is issued, why it is shown once, and how rotation works, see Your credentials.

​
Before a price is payable

An offering can be enabled for your brand and still not be ready to sell. Before a patient can pay for it, four things must be in place. Your storefront can check the result itself: the storefront read answers price_status: available with a list_price once the offering’s price and billing terms are set (items 1 to 3). Item 4 is separate: until your consent documents are configured, the hosted checkout keeps payment locked even when the price is available.
  1. Product copy. Each offering needs a display name and description for your brand. The platform’s starter copy fills every offering that has none yet, in one call, the step your welcome pack shows: POST /v1/account/brands/{brand_id}/starter-merchandising. Send the current starter pack version, 3, as pack_version. Adoption only fills offerings that have no copy yet. An offering that already has copy is skipped and listed as skipped in the response. A 400 naming a different version means the pack has moved on: the refusal’s detail states the version the platform serves now. A 404 means the brand in the path is not one of yours, and nothing was adopted. A 404 with the generic not-found type means the request did not reach the call at all (see Reading a 404).
  2. A price. See Pricing. Until a price is set, the storefront read answers 404 with type commerce/merchandising/not-configured.
  3. Billing terms. How often the price bills and how often the product ships. You choose the billing cadence for each offering, monthly (a charge every month of the medication’s supply) or upfront (one charge for the whole term), with PUT /v1/account/brands/{brand_id}/offerings/{offering_ref}/billing-cadence and the body {"billing": "monthly"} or {"billing": "upfront"}. Only a cadence that suits the offering’s supply is accepted. A 422 explains why a cadence was refused and lists the ones you can choose in compatible_billing. You never set the shipping cadence: it always follows the offering’s supply, and a body that names one is refused. When only one billing cadence suits an offering, the platform sets it for you when the offering is enabled and already has its copy, or when its copy is adopted, whichever comes first, so you need the call only when you have a choice. Your readiness report shows a cadence_compatible check for every offering, and it names this step while a choice is still yours to make. Until billing terms are set, the storefront read answers price_status: pending and the hosted checkout does not take payment.
  4. Your checkout consent documents. Payment stays locked until they are configured. GET /v1/account/brands/{brand_id}/readiness reports whether they are.

​
Before you make your first call

You are ready once you have your API key, your brand id, your member portal address and at least one offering. From there, the Walkthrough takes you from your first call to your first received event, and Connect a Lovable storefront takes you to a first test order.