Developer guide
Headless, hosted or hybrid: choosing a mode
Run the whole patient experience yourself (headless, the Hims/Ro model), let Ambition host it, or mix them per program.
Open the Developer CenterNever send patient information to a sandbox key.
On this deployment: Headless clinical API (patient data): Not available · Headless Connect API: Not available in this environment · Care host: Not built yet
- Headless clinical API (patient data): Not available. What runs now: Nothing for a real patient: the headless patient API is written and has run only against a local synthetic stack; no brand's patient data access is approved in any environment, and the Developer Center's clinical-loop simulator is a script with synthetic ids.
- 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.
Three modes, set per program
| Headless | Hosted | Hybrid | |
|---|---|---|---|
| Site, account, checkout | Yours | Your site sells; care.<brand> does care | Yours |
| Intake, consent, portal, messaging | Yours, on the patient API | Ambition-hosted care site | Yours, with hosted pieces where you choose |
| Patient data on your systems | Yes: you are a business associate | No | Yes |
| Key | phi_server, after the patient data access gate | Standard secret key | phi_server |
| Billing at launch | Mode B: you are merchant of record, fixed fees | Mode A on your connected account | Mode B |
| Consent | Brand-rendered with render receipts | Hosted | Brand-rendered |
| Notifications | You send them from webhooks | Ambition sends them | You send them |
Headless is the default for a brand with engineering. Hosted stays for builder-site brands and brands that will not hold health information. The defaults per program are consent_capture brand_rendered, notification_mode webhook_only, billing_mode brand_mor, idv_mode ambition_inquiry, transmission_release auto and contact_sender brand_domain; any change to a headless program clears its approval until it is approved again.
Status: written, not open. The headless patient API exists on the developer sandbox build and has run only against synthetic data; no brand's patient data access is approved in any environment yet, and there are no live PHI keys.
Async first
Headless serves programs and States whose required modality is asynchronous. Where a State or program needs a video visit, the API answers modality_unavailable_headless until video lands for headless brands.
Who may join
The pilot is invite-only through the physician group. Admitting a patient from your own sign-up (POST /patients/{patientId}/enrollments) is self-serve enrollment, exactly like POST /enrollments in hosted mode: while the program's self-serve enrollment is off (the default) eligibility answers program_self_enrollment_closed and admission is refused with it. A program manager turns it on in Programs > Self-serve enrollment once your physician group approves; an enrollment a patient already holds is kept if it is turned off again. On live data, intake also needs an accepted enrollment for the program and State: refer the patient to your medical group (POST /patients/{patientId}/referrals, the referrals guide), which works whether or not self-serve enrollment is on.