Start building

Developer guide

Hosted mode: the hand-off contract

Hosted mode. Your site sells, your care site does care: links, launch links, return URLs and logins.

Open the Developer Center

Never send patient information to a sandbox key.

On this deployment: Headless Connect API: Not available in this environment · Care host: Not built yet · Self-enrollment on the care host: Not open yet
  • Headless Connect API: Not available in this environment. What runs now: Sandbox-key calls to /api/v1 on the nonproduction deployment with synthetic data: claims scan, formulary, rulebook, the sandbox order preview, delivery reads and replay, and the MCP endpoint, on a deployment whose database has the 20261101090000-range migrations applied (a hard deploy-order dependency the merge gate enforces; ahead of them the rulebook, claims scan, MCP and replay answer 503).
  • Care host: Not built yet. What runs now: Custom hostnames and branded hosted pages for brands with a published builder site.
  • Self-enrollment on the care host: Not open yet. What runs now: Waitlist capture with consent and privacy-notice digest on /storefront/start; prescriber-issued referral invitations. Built but not yet verified end to end and open for no brand: self-enrollment on the care host (/storefront/start?p=<handle>: email code, account, consent recorded by notice digest, admission under brand + program + state enrollment authority, intake for that program) and launch-link redemption (/storefront/launch), behind each brand's hosted.self_enrollment capability row on the deployment's own plane. A brand's production row is set live only by ah_set_brand_capability_state (a platform administrator at AAL2 with a reason, recorded in ah_capability_state_events).

What stays on your site

Your site shows the catalog, approved prices, state availability, scanned copy and the required disclosures verbatim. From the patient's Start click onward, everything happens on your Ambition-hosted care site: the account, consent, entity documents, intake, card setup, messaging, visits and the portal.

  • Collect no health information: no questionnaire, symptom, condition, medication or eligibility answers, and no program-interest form that posts to your systems. A waitlist belongs on your care site's Start page.
  • Put no condition word, program key or health detail in a URL you define. Ambition's links carry opaque handles only.
  • Keep pixels and tags off hand-off pages and off pages about a condition.
  • Hold only what is yours: your customer id as externalReference, an email you already hold, and Ambition's ids, amounts and dates.

Attribution, and links that do not resolve

  • Add ref= to a Start link to attribute the visit: 1 to 512 letters, digits, ., _, ~ or -. The care site keeps it through the program choice and records it on the enrollment it creates. Use an opaque value you can map back, such as a campaign id: never a condition word, an email or anything about the person.
  • Every other query parameter is ignored, utm_* included. The care site passes no marketing parameter on and carries no pixels or tags.
  • A Start link whose p= is not one of your published programs, or is not a program handle at all, shows the visitor a notice that the program is not open on this site and offers what is open. It never starts a different program in its place.
  • A launch link that is expired, already used or unknown says so on the care site and offers sign-in; ask for a fresh one with POST /v1/enrollments/{id}/launch.
A Start link with attribution
https://care.your-brand.example/start?p=prg_0123456789abcdef01234567&ref=spring-launch-email

Server to server

  • POST /v1/enrollments returns a launchUrl: single use, valid for 30 minutes, an opaque token.
  • The token does not sign anyone in. The care site moves it into an HTTP-only cookie, removes it from the address and asks for a one-time email code.
  • If you supplied an email, only a person who proves that address can redeem the link, so a forwarded link cannot bind someone else to your reference. Without one, the binding reads unconfirmed.
  • The answer is identical whether or not the person already has an account.
  • A returnUrl must be an https URL on one of your verified external sites in that plane. It is checked and recorded with the enrollment; the care site does not show the return link yet.
  • Ambition does not email the link. To send back a person who did not finish after it expired, ask for a fresh one with POST /v1/enrollments/{id}/launch (enrollments.relaunch(id) in the SDK). It changes nothing about the enrollment and a retry is safe. When a create answers external_reference_taken, an open enrollment of yours already uses that reference: find its id with GET /v1/enrollments?externalReference= (the one that is not canceled or expired) and relaunch it.
  • An externalReference names one enrollment attempt, not a customer for life. An enrollment nobody continues expires 30 days after it was created, and a canceled or expired enrollment frees its reference, so a returning customer can start again with the same one.

After the hand-off

Link returning patients to these stable care-site addresses; each signs the patient in first and then lands there.

  • /storefront/login?next=%2Fportal
  • /storefront/login?next=%2Fportal%2Forders
  • /storefront/login?next=%2Fportal%2Fmessages
  • /storefront/login?next=%2Fvisits

If your site has its own login, your patients have two: yours, and their care-site account. Sign-in from your login to the care site is not offered yet.