Ambition Health API reference

List every substance the platform has a position on

The authoritative record of what this platform permits, refuses, and permits with conditions. Every row carries the provision that governs it, and every refusal carries a reason in plain language. This endpoint is public and unauthenticated on purpose: an operator should be able to learn what they cannot sell before they sign anything.

Query parameters

Example response · 200

{
  "data": [
    {
      "slug": "example-slug",
      "displayName": "example-display-name",
      "aliases": [
        "example-aliases"
      ],
      "category": "example-category",
      "status": "approved",
      "controlledSchedule": "II",
      "approvedProducts": [
        {
          "brand": "example-brand",
          "application": "example-application",
          "approved": "example-approved"
        }
      ],
      "compounding": {
        "status503a": "example-status503a",
        "status503b": "example-status503b",
        "bulkBasis": "example-bulk-basis",
        "note": "example-note"
      },
      "citation": "example-citation",
      "conditions": [
        "example-conditions"
      ],
      "refusalReason": "example-refusal-reason",
      "reviewBy": "example-review-by"
    }
  ],
  "meta": {
    "requestId": "example_requestId",
    "apiVersion": "example-api-version",
    "environment": "example-environment",
    "formularyVersion": "example-formulary-version",
    "total": 1,
    "nextCursor": "example-next-cursor"
  }
}

Errors

Read one substance, with its citation and refusal reason

Returns the platform's position on a single substance. Also resolves aliases, so `Viagra` and `sildenafil citrate` both reach the `sildenafil` row.

Example response · 200

{
  "data": {
    "slug": "example-slug",
    "displayName": "example-display-name",
    "aliases": [
      "example-aliases"
    ],
    "category": "example-category",
    "status": "approved",
    "controlledSchedule": "II",
    "approvedProducts": [
      {
        "brand": "example-brand",
        "application": "example-application",
        "approved": "example-approved"
      }
    ],
    "compounding": {
      "status503a": "example-status503a",
      "status503b": "example-status503b",
      "bulkBasis": "example-bulk-basis",
      "note": "example-note"
    },
    "citation": "example-citation",
    "conditions": [
      "example-conditions"
    ],
    "refusalReason": "example-refusal-reason",
    "reviewBy": "example-review-by"
  },
  "meta": {
    "requestId": "example_requestId",
    "apiVersion": "example-api-version",
    "environment": "example-environment"
  }
}

Errors

Read the active marketing-claim rulebook

Every rule the claim scanner enforces, with the statute or enforcement instance behind it. Published so that a tenant can audit the gate rather than discover it at publish time. Patterns are not published. A rule with `detection: alias_pair` reads two different substances of an alias group joined together (`aliasGroups` lists which substances each group joins).

Example response · 200

{
  "data": {
    "version": "example-version",
    "description": "example-description",
    "sourceCitation": "example-source-citation",
    "activatedAt": "2026-01-01T00:00:00.000Z",
    "rules": [
      {
        "code": "example-code",
        "severity": "block",
        "category": "example-category",
        "message": "example-message",
        "rewrite": "example-rewrite",
        "citation": "example-citation",
        "rationale": "example-rationale",
        "channels": [
          "example-channels"
        ],
        "detection": "pattern",
        "pairGroup": "example-pair-group"
      }
    ],
    "aliasGroups": [
      {
        "name": "example-name",
        "substances": [
          "example-substances"
        ]
      }
    ]
  },
  "meta": {
    "requestId": "example_requestId",
    "apiVersion": "example-api-version",
    "environment": "example-environment"
  }
}

Errors

List every lifecycle in the product

Every record that moves between named states (a case, an order, a subscription, a site version, a webhook delivery), grouped by product area, with the status values each can hold. Read one in full at `/lifecycles/{id}` to learn what each status means and what can happen next, so a client never has to hard-code a lifecycle from prose.

Query parameters

Example response · 200

{
  "data": {
    "total": 1,
    "areas": [
      {
        "area": "care",
        "title": "example-title",
        "lifecycles": [
          {
            "id": "example_id",
            "title": "example-title",
            "subject": "example-subject",
            "area": "care",
            "states": [
              null
            ]
          }
        ]
      }
    ]
  },
  "meta": {
    "requestId": "example_requestId",
    "apiVersion": "example-api-version",
    "environment": "example-environment"
  }
}

Errors

Read one lifecycle: its states in words and every move

Each state with the words a person is shown, one sentence on what it means, who is being waited on, whether it is final, and every move out of it with who can make it. The database decides whether a move happens; this describes what it will accept.

Example response · 200

{
  "data": {
    "id": "example_id",
    "title": "example-title",
    "subject": "example-subject",
    "area": "care",
    "stored_in": "example-stored_in",
    "event_log": "example-event_log",
    "initial": [
      "example-initial"
    ],
    "terminal": [
      "example-terminal"
    ],
    "states": [
      {
        "state": "example-state",
        "label": "example-label",
        "meaning": "example-meaning",
        "terminal": false,
        "waiting_on": "patient",
        "next": [
          {
            "to": "example-to",
            "label": "example-label",
            "by": [
              null
            ],
            "via": "example-via"
          }
        ]
      }
    ]
  },
  "meta": {
    "requestId": "example_requestId",
    "apiVersion": "example-api-version",
    "environment": "example-environment"
  }
}

Errors

Register an agent platform as an OAuth client

OAuth 2.0 Dynamic Client Registration (RFC 7591) for the MCP endpoint's authorization server. Registers a public client (no secret; PKCE S256 is required at authorization) with one to five exact redirect URIs: HTTPS, or a loopback address for a native client. Registration grants nothing: a client acts for nobody until a signed-in person consents with a fresh second factor. Answers in the RFC 7591 shapes, not the v1 envelope. Discovery: `/.well-known/oauth-authorization-server`.

Request body

Example response · 201

{
  "client_id": "example_client_id",
  "client_id_issued_at": 1,
  "client_name": "example-client_name",
  "redirect_uris": [
    "example-redirect_uris"
  ],
  "grant_types": [
    "example-grant_types"
  ],
  "response_types": [
    "example-response_types"
  ],
  "token_endpoint_auth_method": "none"
}

Errors

Exchange an authorization code or a refresh token

The OAuth 2.1 token endpoint (`application/x-www-form-urlencoded`). `authorization_code` needs the code, the exact redirect URI and the PKCE `code_verifier`; `refresh_token` rotates a single-use refresh token (one presented twice ends the connection). Tokens are bound to this server's MCP endpoint (`resource`, RFC 8707). Access tokens last 15 minutes; a connection lasts at most eight hours, like a console session. Answers in the RFC 6749 shapes, never cached.

Request body

Example response · 200

{
  "access_token": "example-access_token",
  "token_type": "Bearer",
  "expires_in": 1,
  "refresh_token": "example-refresh_token",
  "scope": "example-scope"
}

Errors

Revoke an agent connection

OAuth token revocation (RFC 7009, form body): either token of a connection ends the whole connection. An unknown token is answered 200, as the RFC requires.

Request body

Example response · 200

{}

Errors

Service objectives, measured, and every published incident

Public and unauthenticated. Each objective reports the ratio actually measured over its rolling window rather than the one we would like to claim, and an objective with no observations behind it reports `unmeasured` rather than met. Resolved incidents carry their customer impact and root cause, and the update timeline is append-only.

Example response · 200

{
  "data": {
    "objectives": [
      {
        "component": "example-component",
        "metric": "example-metric",
        "target": 1,
        "windowDays": 1,
        "measured": 1,
        "errorBudgetRemaining": 1,
        "state": "met"
      }
    ],
    "incidents": [
      {
        "reference": "example-reference",
        "title": "example-title",
        "severity": "sev1",
        "component": "example-component",
        "status": "investigating",
        "startedAt": "2026-01-01T00:00:00.000Z",
        "resolvedAt": "2026-01-01T00:00:00.000Z",
        "customerImpact": "example-customer-impact",
        "updates": [
          {
            "status": "example-status",
            "body": "example-body",
            "postedAt": "2026-01-01T00:00:00.000Z"
          }
        ]
      }
    ]
  },
  "meta": {
    "requestId": "example_requestId",
    "apiVersion": "example-api-version",
    "environment": "example-environment"
  }
}

Errors

List a brand's programs with their approved offers

Every program the brand offers on this deployment whose approved offer and approved disclosure both resolve, with the opaque program handle to link the care host's Start page with, the offer exactly as the hosted payment flow bills it, and the digest of the disclosure that must accompany it. A program with no approved offer is omitted rather than shown with a default price. No clinician, program key or clinical content is returned. Public and unauthenticated: no credential is read, the answer is the same for every caller, and it is cacheable (`Cache-Control: public, max-age=60`) with `Access-Control-Allow-Origin: *` and no credentials, so a brand's own site may fetch it from the browser. The brand handle is the brand's stable slug. An unknown brand answers 404 after the same response floor as a known one.

Example response · 200

{
  "data": {
    "brand": {
      "handle": "example-handle",
      "name": "example-name"
    },
    "programs": [
      {
        "handle": "example-handle",
        "name": "example-name",
        "offer": {
          "amountCents": 1,
          "currency": "usd",
          "interval": "week",
          "trialDays": 1,
          "display": "example-display",
          "offerVersion": 1,
          "termsHash": "example-terms-hash",
          "effectiveTo": "example-effective-to"
        },
        "disclosure": {
          "version": "example-version",
          "digest": "example-digest"
        }
      }
    ]
  },
  "meta": {
    "requestId": "example_requestId",
    "apiVersion": "example-api-version",
    "environment": "example-environment"
  }
}

Errors

Read one program's approved offer by its public handle

The same entry the list returns, for one program handle. A handle that names no program of the brand, or a program with no approved offer, answers 404. Public and unauthenticated: no credential is read, the answer is the same for every caller, and it is cacheable (`Cache-Control: public, max-age=60`) with `Access-Control-Allow-Origin: *` and no credentials, so a brand's own site may fetch it from the browser. The brand handle is the brand's stable slug. An unknown brand answers 404 after the same response floor as a known one.

Example response · 200

{
  "data": {
    "handle": "example-handle",
    "name": "example-name",
    "offer": {
      "amountCents": 1,
      "currency": "usd",
      "interval": "week",
      "trialDays": 1,
      "display": "example-display",
      "offerVersion": 1,
      "termsHash": "example-terms-hash",
      "effectiveTo": "example-effective-to"
    },
    "disclosure": {
      "version": "example-version",
      "digest": "example-digest"
    }
  },
  "meta": {
    "requestId": "example_requestId",
    "apiVersion": "example-api-version",
    "environment": "example-environment"
  }
}

Errors

Whether a program is offered in a state

`available`, `video_required` or `unavailable`, with a reason code. It reads the program's current state policy, the California exclusion (always `unavailable`, `state_excluded`), and whether any licensed clinician covers the program there. Coverage is reported as presence only: the answer never names, identifies or counts a clinician. An availability answer is not a medical diagnosis, autonomous eligibility, or production clinical approval: it says only whether the program is offered in that state. Whether a patient can be treated is decided by a licensed clinician on the care host, after intake. Public and unauthenticated: no credential is read, the answer is the same for every caller, and it is cacheable (`Cache-Control: public, max-age=60`) with `Access-Control-Allow-Origin: *` and no credentials, so a brand's own site may fetch it from the browser. The brand handle is the brand's stable slug. An unknown brand answers 404 after the same response floor as a known one.

Query parameters

Example response · 200

{
  "data": {
    "program": "example-program",
    "state": "AL",
    "status": "available",
    "reason": "state_excluded"
  },
  "meta": {
    "requestId": "example_requestId",
    "apiVersion": "example-api-version",
    "environment": "example-environment"
  }
}

Errors

The disclosures a brand's pages must show, verbatim

Every disclosure the builder would require on a hosted page, for the brand's own site: each program's approved disclosure and cancellation terms, its regulatory standing when its substance stands on a regulatory policy, the emergency notice, and the legal documents to link. Each block has a stable id, a digest, the verbatim text and a placement hint, and the response carries the same blocks as a sanitized HTML fragment. The programs are exactly the catalog's; an `approved_disclosure` digest equals the catalog's `disclosure.digest`. A regulatory block is `not_available` when the policy is withdrawn or the substance is held, and the program's availability is then `regulatory_unavailable`. No program key, clinician or clinical content is returned. Public and unauthenticated: no credential is read, the answer is the same for every caller, and it is cacheable (`Cache-Control: public, max-age=60`) with `Access-Control-Allow-Origin: *` and no credentials. An unknown brand answers 404 after the same response floor as a known one.

Query parameters

Example response · 200

{
  "data": {
    "brand": {
      "handle": "example-handle",
      "name": "example-name"
    },
    "program": "example-program",
    "state": "AL",
    "digest": "example-digest",
    "blocks": [
      {
        "id": "example_id",
        "kind": "approved_disclosure",
        "program": "example-program",
        "status": "required",
        "reason": "announced",
        "version": "example-version",
        "digest": "example-digest",
        "text": "example-text",
        "links": [
          {
            "kind": "privacy",
            "label": "example-label",
            "url": "example-url",
            "version": "example-version",
            "digest": "example-digest",
            "legalEntityName": "example-legal-entity-name"
          }
        ],
        "placement": "with_price",
        "draft": false
      }
    ],
    "html": "example-html"
  },
  "meta": {
    "requestId": "example_requestId",
    "apiVersion": "example-api-version",
    "environment": "example-environment"
  }
}

Errors

The brand's care network, for its consumer terms

The legal names of the physician groups that cover the brand (with their clinicians' licensed states and their messaging SLA), the network pharmacies, and the labs. Name them in your consumer terms. Public, PHI-free and cacheable; no clinician, count, address or identifier. California is excluded.

Query parameters

Example response · 200

{
  "data": {
    "brand": {
      "handle": "example-handle",
      "name": "example-name"
    },
    "state": "AL",
    "physicianGroups": [
      {
        "legalName": "example-legal-name",
        "doingBusinessAs": "example-doing-business-as",
        "formationState": "example-formation-state",
        "states": [
          "example-states"
        ],
        "messagingSla": {
          "routineResponseHours": 1,
          "urgentResponseHours": 1
        }
      }
    ],
    "pharmacies": [
      {
        "name": "example-name",
        "states": [
          "example-states"
        ],
        "coldChain": false
      }
    ],
    "labs": [
      {
        "legalName": "example-legal-name",
        "cliaNumber": "example-clia-number"
      }
    ],
    "labsNote": "example-labs-note",
    "californiaExcluded": true
  },
  "meta": {
    "requestId": "example_requestId",
    "apiVersion": "example-api-version",
    "environment": "example-environment"
  }
}

Errors

Ask for a copy of your records (patients)

The Ambition-run records request, for a patient whose brand cannot serve them. If the email is the one Ambition verified for a patient of the brand, a code is sent to it from the physician group. The answer is the same either way.

Request body

Example response · 202

{
  "data": {
    "requestToken": "example-request-token",
    "expiresAt": "2026-01-01T00:00:00.000Z"
  },
  "meta": {
    "requestId": "example_requestId",
    "apiVersion": "example-api-version",
    "environment": "example-environment"
  }
}

Errors

Confirm a records request with the emailed code

Opens a right-of-access request with the physician group, answered within 30 days. Five attempts per code.

Request body

Example response · 200

{
  "data": {
    "status": "opened",
    "reference": "example-reference",
    "dueAt": "2026-01-01T00:00:00.000Z"
  },
  "meta": {
    "requestId": "example_requestId",
    "apiVersion": "example-api-version",
    "environment": "example-environment"
  }
}

Errors

The program's current questionnaire, as FHIR R4

The published intake (or check-in) questionnaire of a program, as a FHIR R4 Questionnaire for your own intake screens: items with linkId, type, text, required, answerOption and enableWhen, plus Ambition extensions for the stop rules (show their patient message when the answers match), the consent scopes the program requires, the identity gate and, with `state`, the modality there. `id` is the version id and `version` its content hash; submit against both. Public and non-PHI: cacheable for 60 seconds with an ETag of the content hash.

Query parameters

Example response · 200

{
  "data": {
    "brand": {
      "handle": "example-handle",
      "name": "example-name"
    },
    "programHandle": "example-program-handle",
    "questionnaire": {
      "resourceType": "Questionnaire",
      "id": "example_id",
      "version": "example-version",
      "status": "active",
      "item": [
        {}
      ]
    }
  },
  "meta": {
    "requestId": "example_requestId",
    "apiVersion": "example-api-version",
    "environment": "example-environment"
  }
}

Errors

One questionnaire version, as FHIR R4 (immutable)

A published or superseded questionnaire version by id, as a FHIR R4 Questionnaire. A version never changes, so this is the reference for answers you stored. Public and non-PHI.

Example response · 200

{
  "data": {
    "brand": {
      "handle": "example-handle",
      "name": "example-name"
    },
    "programHandle": "example-program-handle",
    "questionnaire": {
      "resourceType": "Questionnaire",
      "id": "example_id",
      "version": "example-version",
      "status": "active",
      "item": [
        {}
      ]
    }
  },
  "meta": {
    "requestId": "example_requestId",
    "apiVersion": "example-api-version",
    "environment": "example-environment"
  }
}

Errors

The physician group's consent documents for a program and state

The legal kit a patient accepts before intake, issued by the physician group covering the brand: telehealth consent (your brand named as third-party beneficiary), the Notice of Privacy Practices acknowledgment, the compounded medication and interim peptide policy acknowledgment (programs that sell a formulary substance), the cash-pay and Medicare TrOOP certification, clinician-messaging consent and the AI-use disclosure. Each with its verbatim text and label, their SHA-256 digests, presentation rules and the capture mode in force. Public and non-PHI.

Query parameters

Example response · 200

{
  "data": {
    "brand": {
      "handle": "example-handle",
      "name": "example-name"
    },
    "program": "example-program",
    "state": "example-state",
    "locale": "example-locale",
    "classification": "synthetic",
    "documents": [
      {
        "scope": "telehealth_consent",
        "title": "example-title",
        "available": false,
        "documentId": "00000000-0000-4000-8000-00000000e001",
        "version": 1,
        "jurisdiction": "example-jurisdiction",
        "locale": "example-locale",
        "documentTitle": "example-document-title",
        "sha256": "example-sha256",
        "body": "example-body",
        "labelText": "example-label-text",
        "labelSha256": "example-label-sha256",
        "presentation": {
          "separateCheckbox": false,
          "noPrefill": false,
          "mustDisplayFullText": false
        },
        "brandBeneficiary": false,
        "sandboxTemplate": false,
        "legalEntityName": "example-legal-entity-name",
        "effectiveAt": "2026-01-01T00:00:00.000Z",
        "captureMode": "brand_rendered"
      }
    ]
  },
  "meta": {
    "requestId": "example_requestId",
    "apiVersion": "example-api-version",
    "environment": "example-environment"
  }
}

Errors

The versioned emergency screen for safety reports

The emergency copy and the three seriousness questions to show before a patient reports a side effect or a product problem. Echo `version` as `emergencyScreenVersion`. The same for every brand; public and non-PHI.

Example response · 200

{
  "data": {
    "version": "example-version",
    "sha256": "example-sha256",
    "draft": false,
    "emergencyText": "example-emergency-text",
    "questions": [
      {
        "id": "emergency_symptoms",
        "text": "example-text",
        "answers": [
          "example-answers"
        ]
      }
    ],
    "medwatchNotice": "example-medwatch-notice"
  },
  "meta": {
    "requestId": "example_requestId",
    "apiVersion": "example-api-version",
    "environment": "example-environment"
  }
}

Errors

A program's regulatory standing: substance, policy, products, state availability, labs

Everything your storefront needs to list or pull a regulated SKU: the substance and the regulatory policy it stands on (status, label to show verbatim, citation, Appendix B routes), the patient disclosure with its version and digest, the active pharmacy products with their standing, availability in every state with a reason, and the program's required labs. Subscribe to `formulary.policy_changed` and `formulary.state_availability_changed` and re-read this when one arrives. Public regulatory reference data: no patient, clinician or price. Cacheable (`Cache-Control: public, max-age=60`) with `Access-Control-Allow-Origin: *`; an unknown brand answers 404 after the same response floor as a known one.

Example response · 200

{
  "data": {
    "brand": {
      "handle": "example-handle",
      "name": "example-name"
    },
    "program": {
      "handle": "example-handle",
      "name": "example-name",
      "substance": {
        "slug": "example-slug",
        "name": "example-name",
        "formularyStatus": "example-formulary-status",
        "singleIngredient": true
      },
      "policy": {
        "key": "example-key",
        "status": "announced",
        "regulatoryStatus": "example-regulatory-status",
        "label": "example-label",
        "citation": "example-citation",
        "sourceUrl": "example-source-url",
        "allowedRoutes": [
          "example-allowed-routes"
        ],
        "intermittentCourse": false
      },
      "disclosure": {
        "version": "example-version",
        "digest": "example-digest",
        "text": "example-text",
        "reportingInstruction": "example-reporting-instruction"
      },
      "products": [
        {
          "productId": "00000000-0000-4000-8000-00000000e001",
          "form": "example-form",
          "route": "example-route",
          "strength": "example-strength",
          "standing": "policy_withdrawn"
        }
      ],
      "regulatoryGated": false,
      "states": [
        {
          "state": "AL",
          "available": false,
          "reason": "policy_not_in_effect"
        }
      ],
      "requiredLabs": [
        {
          "key": "example-key",
          "label": "example-label",
          "kind": "baseline",
          "loincCodes": [
            "example-loinc-codes"
          ],
          "minCodesPresent": 1,
          "maxAgeDays": 1,
          "intervalDays": 1,
          "noticeDays": 1,
          "acceptedSources": [
            "brand_arranged"
          ]
        }
      ]
    }
  },
  "meta": {
    "requestId": "example_requestId",
    "apiVersion": "example-api-version",
    "environment": "example-environment"
  }
}

Errors

Evaluate marketing copy against the rulebook before you publish it

Runs the same engine, against the same active rulebook, that gates publication inside the platform — so a result here is the result you will get at publish time. Rules that apply only to other channels than `context` are not applied. Each hit carries the matched text, the provision behind the rule, and a compliant rewrite where one exists. With `programKey`, the copy is judged for that program: when it sells a substance on a regulatory policy, the rules for such a program's pages run too (`regulatedContext`); without it they run whenever your brand has such a program, as they would on its pages. Every scan stores a receipt (`receiptId`) with the rulebook version, the channel, the request id and the SHA-256 of the text; the text itself, and the matched fragments, are stored only when `retainText` is true. `requiredDisclosures` are checked by exact text against their current approved version. This checks claims only: the builder's price-book conflict check does not run here, so render prices from the catalog rather than writing them into copy. Do not include patient information in the text.

Request body

Example response · 200

{
  "data": {
    "outcome": "pass",
    "blocked": 1,
    "warned": 1,
    "hits": [
      {
        "code": "example-code",
        "severity": "block",
        "category": "example-category",
        "message": "example-message",
        "rewrite": "example-rewrite",
        "citation": "example-citation",
        "match": "example-match"
      }
    ],
    "rulebookVersion": "example-rulebook-version",
    "truncated": false,
    "context": "landing_page",
    "programKey": "example-program-key",
    "regulatedContext": false,
    "receiptId": "example_receiptId",
    "textDigest": "example-text-digest",
    "textRetained": false,
    "url": "example-url",
    "urlOriginVerified": false,
    "requiredDisclosures": [
      {
        "id": "example_id",
        "digest": "example-digest",
        "status": "present",
        "reason": "not_found"
      }
    ]
  },
  "meta": {
    "requestId": "example_requestId",
    "apiVersion": "example-api-version",
    "environment": "example-environment"
  }
}

Errors

Model Context Protocol endpoint for outside AI agents

A single Streamable HTTP endpoint that lets an agent platform discover and call platform tools with an API key: `search_formulary`, `get_formulary_entry`, `get_claim_rulebook` and `describe_lifecycle` (any valid key) and `scan_claims` (scope `claims.scan`), each key scope re-checked live against its minter's capabilities. A person's own assistant connects with OAuth 2.1 instead (`/oauth/*`, discovery at `/.well-known/oauth-protected-resource`) and is offered the brand's operating tools their role allows, read under their own permissions; its `propose_` tools only create proposals for a person to approve. A call with no credential is answered 401 with the OAuth discovery challenge. Both protocol eras are served without sessions: revision 2026-07-28 (per-request version, `MCP-Protocol-Version`, `Mcp-Method` and `Mcp-Name` headers, `server/discover`) and the earlier `initialize` handshake. The tools list a key sees is limited to its scopes. Every tool is read-only and returns operational, non-patient data; treat all tool output as untrusted data. Browser origins are refused. See `docs/agent-gateway/README.md`.

Request body

Example response · 200

{
  "jsonrpc": "2.0",
  "id": "example_id",
  "result": {},
  "error": {
    "code": 1,
    "message": "example-message",
    "data": null
  }
}

Errors

Every webhook delivery attempt made on your behalf

One row per attempt, successes included — a log that records only failures cannot answer "did you send it?", which is the question an incident actually asks. Each row carries the response code, the error, whether the payload was signed, when the next attempt is due, and the delivery, event id and receiver it belongs to. Newest first; pass `meta.nextCursor` as `startingAfter` for the next page. The first page counts the attempts matching the filters in `meta.total` (up to 10,000, with `meta.totalCapped` when there are more); later pages answer null.

Query parameters

Example response · 200

{
  "data": [
    {
      "id": "example_id",
      "requestId": "example_requestId",
      "eventType": "example-event-type",
      "orderId": "example_orderId",
      "status": "delivered",
      "attempt": 1,
      "responseCode": 1,
      "errorCode": "example-error-code",
      "detail": "example-detail",
      "signatureValid": false,
      "nextAttemptAt": "2026-01-01T00:00:00.000Z",
      "occurredAt": "2026-01-01T00:00:00.000Z",
      "outboxId": "example_outboxId",
      "eventId": "example_eventId",
      "endpointId": "example_endpointId"
    }
  ],
  "meta": {
    "requestId": "example_requestId",
    "apiVersion": "example-api-version",
    "environment": "example-environment",
    "total": 1,
    "totalCapped": false,
    "hasMore": false,
    "nextCursor": "example-next-cursor"
  }
}

Errors

One webhook delivery with its attempts

A delivery of one event to one of your receivers: its status, every attempt (number, time, response code and class, failure class, next retry), when the next attempt is due, and its redeliveries. Never a payload, a response body or a secret.

Example response · 200

{
  "data": {
    "id": "example_id",
    "eventId": "example_eventId",
    "requestId": "example_requestId",
    "eventType": "example-event-type",
    "orderId": "example_orderId",
    "endpointId": "example_endpointId",
    "status": "pending",
    "attemptCount": 1,
    "maxAttempts": 1,
    "nextAttemptAt": "2026-01-01T00:00:00.000Z",
    "createdAt": "2026-01-01T00:00:00.000Z",
    "deliveredAt": "2026-01-01T00:00:00.000Z",
    "replayOf": "example-replay-of",
    "replayReason": "example-replay-reason",
    "attempts": [
      {
        "attempt": 1,
        "occurredAt": "2026-01-01T00:00:00.000Z",
        "status": "delivered",
        "responseCode": 1,
        "responseClass": "1xx",
        "failureClass": "example-failure-class",
        "signatureValid": false,
        "nextAttemptAt": "2026-01-01T00:00:00.000Z"
      }
    ],
    "redeliveries": [
      {
        "id": "example_id",
        "status": "pending",
        "createdAt": "2026-01-01T00:00:00.000Z"
      }
    ]
  },
  "meta": {
    "requestId": "example_requestId",
    "apiVersion": "example-api-version",
    "environment": "example-environment"
  }
}

Errors

Send a delivered or dead-lettered event again, without opening a support ticket

Queues a fresh attempt at the same event for the receiver it went to: by `outboxId`, or by the `eventId` your receiver saw (with `endpointId` when the event went to several receivers). The event id and payload are preserved, so a receiver that deduplicates on `ambition-event-id` will not act twice. Works on a delivered delivery and on a dead-lettered one; a delivery still being retried, or a receiver that is paused or disabled, is refused. Asking again while the redelivery is queued returns it and costs nothing. Naming a dead-lettered delivery's `outboxId` after it was replayed returns that replay (`created: false`), even once it was delivered: redeliver by `eventId` to send the newest delivery again. A clinical event needs a phi_server key with `clinical_events.read`, a verified clinical receiver and the patient data gate now, and each such request is recorded in the access log with your key as the actor. The reason is recorded against the redelivery; the budget is per API key.

Request body

Example response · 200

{
  "data": {
    "outboxId": "example_outboxId",
    "requestId": "example_requestId",
    "status": "example-status",
    "replayOf": "example-replay-of",
    "eventId": "example_eventId",
    "endpointId": "example_endpointId",
    "eventType": "example-event-type",
    "created": false
  },
  "meta": {
    "requestId": "example_requestId",
    "apiVersion": "example-api-version",
    "environment": "example-environment"
  }
}

Errors

Receive a signed pharmacy status callback

Partner-only machine endpoint. The raw body is authenticated with the pharmacy contract's versioned HMAC secret; timestamp and event headers are mandatory, replay-bounded, and matched to the body before an immutable receipt or order transition is recorded. A cancellation Ambition sent is a request until the pharmacy answers: `canceled` confirms it and `cancel_denied` (with a reason code) refuses it, leaving the order where it is. A shipped status may carry the carrier and tracking number, which the order records. The whole partner contract, including what Ambition sends the pharmacy, is published at GET /api/v1/pharmacy/order-api.

Request body

Example response · 202

{
  "ok": false,
  "outcome": "example-outcome"
}

Errors

Create a deterministic synthetic order preview

Models the order path end to end against synthetic data. Nothing is prescribed, transmitted to a pharmacy, or charged. A console-session route: it needs a same-origin request from a signed-in tenant workforce member and does not accept an API key.

Requires an Idempotency-Key header of 16–255 characters. Replays for 24 hours; reusing a key with a different body returns 409 rather than applying the second request.

Request body

Example response · 200

{
  "data": {},
  "meta": {
    "requestId": "example_requestId",
    "apiVersion": "example-api-version",
    "environment": "example-environment",
    "replayed": false
  }
}

Errors

Simulate a clinician's decision on a sandbox enrollment

Sandbox only. Stands in for the clinician who does not exist on the developer sandbox: moves one of your sandbox enrollments to `approved`, `needs_info`, `not_approved` or `canceled` in a single transition, so your receivers get the same `enrollment.status_changed` webhook (one per subscribed receiver) and `GET /v1/enrollments/{id}` the same status a real decision would produce. Nothing clinical is created: no case, clinician or prescription. Run the full test patient flow first: create the enrollment, open its `launchUrl` on your sandbox care host and verify a test email; then simulate the decision. `canceled` also works before that. Asking for the status the enrollment already holds changes nothing (`meta.changed: false`) and sends no webhook, so a retry is safe. Requires a sandbox secret key (`ak_sandbox_`) with `enrollments.write`; a live key is refused 403, and the database refuses any enrollment that is not synthetic sandbox data. Status is shown exactly as the enrollment read shows it: without your business associate agreement and downstream-systems attestation in force the decision reads `in_progress`, and no `enrollment.status_changed` is sent.

Request body

Example response · 200

{
  "data": {
    "id": "00000000-0000-4000-8000-00000000e001",
    "externalReference": "example-external-reference",
    "status": "created",
    "binding": "confirmed",
    "createdAt": "2026-01-01T00:00:00.000Z",
    "updatedAt": "2026-01-01T00:00:00.000Z"
  },
  "meta": {
    "requestId": "example_requestId",
    "apiVersion": "example-api-version",
    "environment": "example-environment",
    "outcome": "approved",
    "changed": false
  }
}

Errors

Your brand's catalog, for server callers

The same document as `GET /catalog/{brand}/programs`, for the key's own brand and environment. Use it from a backend that already holds a key; the public endpoint needs none. The answer is not cached.

Example response · 200

{
  "data": {
    "brand": {
      "handle": "example-handle",
      "name": "example-name"
    },
    "programs": [
      {
        "handle": "example-handle",
        "name": "example-name",
        "offer": {
          "amountCents": 1,
          "currency": "usd",
          "interval": "week",
          "trialDays": 1,
          "display": "example-display",
          "offerVersion": 1,
          "termsHash": "example-terms-hash",
          "effectiveTo": "example-effective-to"
        },
        "disclosure": {
          "version": "example-version",
          "digest": "example-digest"
        }
      }
    ]
  },
  "meta": {
    "requestId": "example_requestId",
    "apiVersion": "example-api-version",
    "environment": "example-environment"
  }
}

Errors

Start an enrollment and get a launch link to the care host

Creates an enrollment for your own customer in a program and state, and returns a single-use launch link to your brand's care host, where the person proves their email, consents, completes intake and saves a card. Name the program by its catalog handle (or its key) and the state the person will be cared for in; the same authority the care host applies decides whether it is offered there, so California, a state the program is not offered in, or one no licensed clinician covers is refused 422 `program_unavailable_in_state`. In production a program and state the physician network has not yet approved for enrollment is refused 422 `program_awaiting_network_approval` instead: that one is not recorded against the key, so the same request works once the approval is in force. `Idempotency-Key` is required: a retry with the same key and body returns the same enrollment with a freshly minted launch link (`meta.replayed: true`); the earlier link stays valid until it expires. The answer is identical whether or not the email has an account. Brand and environment always come from the key: a sandbox key creates and reads only sandbox enrollments of its own brand, and another brand's enrollment is indistinguishable from one that does not exist.

Requires an Idempotency-Key header of 16–255 characters. Replays for 24 hours; reusing a key with a different body returns 409 rather than applying the second request.

Request body

Example response · 201

{
  "data": {
    "id": "00000000-0000-4000-8000-00000000e001",
    "externalReference": "example-external-reference",
    "status": "created",
    "binding": "confirmed",
    "createdAt": "2026-01-01T00:00:00.000Z",
    "updatedAt": "2026-01-01T00:00:00.000Z",
    "launchUrl": "example-launch-url",
    "launchExpiresAt": "2026-01-01T00:00:00.000Z"
  },
  "meta": {
    "requestId": "example_requestId",
    "apiVersion": "example-api-version",
    "environment": "example-environment",
    "replayed": false
  }
}

Errors

Get a fresh launch link for an open enrollment

Mints a new single-use launch link to your brand's care host for one of your open enrollments created through the API, so you can send back a person who did not finish after the first link expired (links last 30 minutes, and Ambition does not email them) and after the create's Idempotency-Key window closed. It changes nothing about the enrollment: it does not rebind it, and only the person bound to it, or for an unredeemed enrollment the person who proves the email you supplied, can redeem the link. Earlier links stay valid until they expire. Takes no body and no Idempotency-Key: a retry mints another link to the same enrollment. A canceled or expired enrollment has no link (409 `enrollment_closed`); start a new one with `POST /enrollments`, which may carry the same `externalReference`. Once the person has started intake there is no new link either, whatever the enrollment's state (409 `enrollment_link_unavailable`, one answer for every state `GET` reads as `in_progress`): the person continues by signing in on your care host. Brand and environment always come from the key: a sandbox key creates and reads only sandbox enrollments of its own brand, and another brand's enrollment is indistinguishable from one that does not exist.

Example response · 200

{
  "data": {
    "id": "00000000-0000-4000-8000-00000000e001",
    "launchUrl": "example-launch-url",
    "launchExpiresAt": "2026-01-01T00:00:00.000Z"
  },
  "meta": {
    "requestId": "example_requestId",
    "apiVersion": "example-api-version",
    "environment": "example-environment"
  }
}

Errors

List your enrollments by reference or change time

Your brand's enrollments in the key's environment, oldest change first, filtered by your `externalReference` and by `updatedSince`, with cursor pagination. Poll with `updatedSince` set to the last `updatedAt` you saw. Status is coarse and treated as PHI: the intake and decision states are shown only with your brand's business associate agreement and downstream-systems attestation in force and minimum-necessary patient access held by the key's creator; otherwise they read `in_progress`. No answer carries a patient, a program, an email, an intake answer or a clinical reason. Every read is recorded as an access event. Brand and environment always come from the key: a sandbox key creates and reads only sandbox enrollments of its own brand, and another brand's enrollment is indistinguishable from one that does not exist.

Query parameters

Example response · 200

{
  "data": [
    {
      "id": "00000000-0000-4000-8000-00000000e001",
      "externalReference": "example-external-reference",
      "status": "created",
      "binding": "confirmed",
      "createdAt": "2026-01-01T00:00:00.000Z",
      "updatedAt": "2026-01-01T00:00:00.000Z"
    }
  ],
  "meta": {
    "requestId": "example_requestId",
    "apiVersion": "example-api-version",
    "environment": "example-environment",
    "hasMore": false,
    "nextCursor": "example-next-cursor"
  }
}

Errors

Read one enrollment's coarse status

One enrollment of your brand in the key's environment. Status is coarse and treated as PHI: the intake and decision states are shown only with your brand's business associate agreement and downstream-systems attestation in force and minimum-necessary patient access held by the key's creator; otherwise they read `in_progress`. No answer carries a patient, a program, an email, an intake answer or a clinical reason. Every read is recorded as an access event. Brand and environment always come from the key: a sandbox key creates and reads only sandbox enrollments of its own brand, and another brand's enrollment is indistinguishable from one that does not exist.

Example response · 200

{
  "data": {
    "id": "00000000-0000-4000-8000-00000000e001",
    "externalReference": "example-external-reference",
    "status": "created",
    "binding": "confirmed",
    "createdAt": "2026-01-01T00:00:00.000Z",
    "updatedAt": "2026-01-01T00:00:00.000Z"
  },
  "meta": {
    "requestId": "example_requestId",
    "apiVersion": "example-api-version",
    "environment": "example-environment"
  }
}

Errors

Backfill the webhook events of your brand

Events in the order Ambition recorded them, after an opaque cursor: catch a receiver up after downtime or seed a new one. `tier=standard` (default, `events.read`) lists commerce and enrollment events and never names a patient. `tier=clinical` needs `clinical_events.read` on a phi_server key and lists the refs-only `clinical.*` events of your API patients under the delivery rules: your patient data access open and unsuspended and, for a case event, your BAA covering the case's physician group now. A held event appears once it is released. Each event's `id` equals the `ambition-event-id` of its deliveries. Clinical pages are recorded in the access log with your key as the actor.

Query parameters

Example response · 200

{
  "data": [
    {
      "id": "example_id",
      "type": "example-type",
      "livemode": false,
      "schemaVersion": "example-schema-version",
      "data": {},
      "recordedAt": "2026-01-01T00:00:00.000Z"
    }
  ],
  "meta": {
    "requestId": "example_requestId",
    "apiVersion": "example-api-version",
    "environment": "example-environment",
    "tier": "standard",
    "hasMore": false,
    "nextCursor": "example-next-cursor"
  }
}

Errors

Whether your patient data access is enabled, item by item

The patient data access checklist for the key's brand on this deployment's plane: the business associate agreement with the physician group, the privacy officer's frontend attestation, platform PHI terms (and merchant-of-record terms when a headless program bills with you as merchant), the commerce-terms and no-research-use-only commitments, the downstream vendor inventory, on a real-data deployment a verified sending domain (a coarse reason, never the domain itself), and the network approval; plus the kill switch, launch controls and the latest PHI page scan, and whether this deployment is admitting patients yet (`admittingPatients`). Any phi_server key may read it; a standard key gets 403 `phi_key_required`. Contains no patient data and no names.

Example response · 200

{
  "data": {
    "environment": "sandbox",
    "enabled": false,
    "phiAccess": "full",
    "admittingPatients": false,
    "suspended": false,
    "completeCount": 1,
    "requiredCount": 1,
    "items": [
      {
        "key": "baa",
        "state": "complete",
        "reason": "example-reason",
        "detail": {}
      }
    ],
    "launchControls": {
      "required": false,
      "missing": [
        "example-missing"
      ]
    },
    "scan": {
      "state": "none",
      "ranAt": "2026-01-01T00:00:00.000Z",
      "findings": 1,
      "cureEndsAt": "2026-01-01T00:00:00.000Z"
    },
    "evaluatedAt": "2026-01-01T00:00:00.000Z"
  },
  "meta": {
    "requestId": "example_requestId",
    "apiVersion": "example-api-version",
    "environment": "example-environment"
  }
}

Errors

Create a patient (your account is their identity)

Creates a delegated patient for your brand: an Ambition patient record bound to your externalId, with no Ambition login (a synthetic, non-routable identity). The same person in two brands is two patients. The email and phone are recorded as brand-asserted and never count as verified; demographics, when sent, are brand-asserted until identity verification matches them. 201 with the patient; 409 `patient_exists` with the existing id when the externalId or email is already your patient; 409 `hosted_patient_requires_link` when the email belongs to a patient who signed up on your care host. Needs Idempotency-Key and the patient headers. `Ambition-Patient-Auth: otp` is refused (401 `patient_sign_in_unverified`): a patient being created has no Ambition sign-in session; send the method your own sign-up used. A replay (the same Idempotency-Key and body) answers 201 with `meta.replayed` and only the patient's `id`, `externalId`, `status` and `revision`: no demographics are kept with the key. Read the rest with GET /patients/{patientId}.

Requires an Idempotency-Key header of 16–255 characters. Replays for 24 hours; reusing a key with a different body returns 409 rather than applying the second request.

Request body

Example response · 201

{
  "data": {
    "id": "00000000-0000-4000-8000-00000000e001",
    "externalId": "example_externalId",
    "status": "active",
    "revision": 1,
    "residenceState": "AL",
    "createdAt": "2026-01-01T00:00:00.000Z",
    "updatedAt": "2026-01-01T00:00:00.000Z",
    "demographics": {
      "legalName": "example-legal-name",
      "dateOfBirth": "example-date-of-birth",
      "phone": "example-phone",
      "shippingAddress": {
        "line1": "example-line1",
        "line2": "example-line2",
        "city": "example-city",
        "state": "AL",
        "postalCode": "example-postal-code",
        "country": "US"
      },
      "source": "brand_asserted",
      "version": 1
    },
    "contactPoints": [
      {
        "kind": "email",
        "value": "example-value",
        "verifiedBy": "brand_asserted",
        "verifiedAt": "2026-01-01T00:00:00.000Z"
      }
    ],
    "contactVerified": false,
    "identityVerified": false
  },
  "meta": {
    "requestId": "example_requestId",
    "apiVersion": "example-api-version",
    "environment": "example-environment",
    "replayed": false
  }
}

Errors

Find your patient by externalId

Your active patient with that externalId, as a one-element list, or an empty list. Exact match only. With `Ambition-Patient-Auth: otp`, `Ambition-Patient-Session` must be a current Ambition sign-in session reference of the patient found, from this key; otherwise 401 `patient_sign_in_unverified`.

Query parameters

Example response · 200

{
  "data": [
    {
      "id": "00000000-0000-4000-8000-00000000e001",
      "externalId": "example_externalId",
      "status": "active",
      "revision": 1
    }
  ],
  "meta": {
    "requestId": "example_requestId",
    "apiVersion": "example-api-version",
    "environment": "example-environment"
  }
}

Errors

Read a patient

The patient's record as your brand may see it: reference, demographics, contact points with who verified each, and verification state. Audited.

Example response · 200

{
  "data": {
    "id": "00000000-0000-4000-8000-00000000e001",
    "externalId": "example_externalId",
    "status": "active",
    "revision": 1,
    "residenceState": "AL",
    "createdAt": "2026-01-01T00:00:00.000Z",
    "updatedAt": "2026-01-01T00:00:00.000Z",
    "demographics": {
      "legalName": "example-legal-name",
      "dateOfBirth": "example-date-of-birth",
      "phone": "example-phone",
      "shippingAddress": {
        "line1": "example-line1",
        "line2": "example-line2",
        "city": "example-city",
        "state": "AL",
        "postalCode": "example-postal-code",
        "country": "US"
      },
      "source": "brand_asserted",
      "version": 1
    },
    "contactPoints": [
      {
        "kind": "email",
        "value": "example-value",
        "verifiedBy": "brand_asserted",
        "verifiedAt": "2026-01-01T00:00:00.000Z"
      }
    ],
    "contactVerified": false,
    "identityVerified": false
  },
  "meta": {
    "requestId": "example_requestId",
    "apiVersion": "example-api-version",
    "environment": "example-environment"
  }
}

Errors

Update contact, demographics or shipping address

Send `If-Match: <revision>`. A changed email or phone is brand-asserted again and needs a new contact verification. When an Ambition-verified email is replaced, Ambition sends the previous address a neutral notice, asynchronously, with no new address, no link and nothing about care; a brand-asserted email gets none. The legal name and date of birth change only while they are your assertion; once identity verification matched them, or while a prescription is in progress, 409 `identity_fields_locked` (an amendment the care team reviews).

Requires an Idempotency-Key header of 16–255 characters. Replays for 24 hours; reusing a key with a different body returns 409 rather than applying the second request.

Request body

Example response · 200

{
  "data": {
    "id": "00000000-0000-4000-8000-00000000e001",
    "externalId": "example_externalId",
    "status": "active",
    "revision": 1,
    "residenceState": "AL",
    "createdAt": "2026-01-01T00:00:00.000Z",
    "updatedAt": "2026-01-01T00:00:00.000Z",
    "demographics": {
      "legalName": "example-legal-name",
      "dateOfBirth": "example-date-of-birth",
      "phone": "example-phone",
      "shippingAddress": {
        "line1": "example-line1",
        "line2": "example-line2",
        "city": "example-city",
        "state": "AL",
        "postalCode": "example-postal-code",
        "country": "US"
      },
      "source": "brand_asserted",
      "version": 1
    },
    "contactPoints": [
      {
        "kind": "email",
        "value": "example-value",
        "verifiedBy": "brand_asserted",
        "verifiedAt": "2026-01-01T00:00:00.000Z"
      }
    ],
    "contactVerified": false,
    "identityVerified": false
  },
  "meta": {
    "requestId": "example_requestId",
    "apiVersion": "example-api-version",
    "environment": "example-environment",
    "replayed": false
  }
}

Errors

Close the patient's API access

The record stays with the physician group; the patient can still reach it through the Ambition records request. Refused while a prescription is in progress. Later calls for the patient answer 404.

Requires an Idempotency-Key header of 16–255 characters. Replays for 24 hours; reusing a key with a different body returns 409 rather than applying the second request.

Request body

Example response · 200

{
  "data": {
    "id": "00000000-0000-4000-8000-00000000e001",
    "status": "deactivated"
  },
  "meta": {
    "requestId": "example_requestId",
    "apiVersion": "example-api-version",
    "environment": "example-environment",
    "replayed": false
  }
}

Errors

Send an Ambition contact code

Ambition generates a six-digit code and sends it to the patient's email from your verified domain (or the physician group's sender). You never see the code: relay what the patient types to `/confirm`. Use it as your sign-up code; it proves the patient controls that email, but it is not an Ambition sign-in: afterwards send the method your own sign-in used, not `otp` (`otp` needs an Ambition sign-in link's sessionReference). Required once before the first prescription is transmitted (hold `contact_unverified`). Ten minutes, five attempts, five codes per patient per hour. On the sandbox the email is caught, never delivered: read the code with `GET /sandbox/patients/{patientId}/messages`.

Requires an Idempotency-Key header of 16–255 characters. Replays for 24 hours; reusing a key with a different body returns 409 rather than applying the second request.

Request body

Example response · 201

{
  "data": {
    "verificationId": "00000000-0000-4000-8000-00000000e001",
    "status": "sent",
    "channel": "email",
    "destinationHint": "example-destination-hint",
    "expiresAt": "2026-01-01T00:00:00.000Z",
    "attemptsRemaining": 1
  },
  "meta": {
    "requestId": "example_requestId",
    "apiVersion": "example-api-version",
    "environment": "example-environment",
    "replayed": false
  }
}

Errors

Confirm the code the patient typed

`verified`, or `invalid_code` (with attempts remaining), `expired`, `locked` or `undelivered`. A wrong code counts as an attempt.

Requires an Idempotency-Key header of 16–255 characters. Replays for 24 hours; reusing a key with a different body returns 409 rather than applying the second request.

Request body

Example response · 200

{
  "data": {
    "verificationId": "00000000-0000-4000-8000-00000000e001",
    "status": "sent",
    "channel": "email",
    "destinationHint": "example-destination-hint",
    "expiresAt": "2026-01-01T00:00:00.000Z",
    "attemptsRemaining": 1
  },
  "meta": {
    "requestId": "example_requestId",
    "apiVersion": "example-api-version",
    "environment": "example-environment",
    "replayed": false
  }
}

Errors

Verify identity (BYO vendor or Ambition-run)

`{mode: byo, vendor, inquiryId}`: you ran the inquiry at your allowlisted vendor with reference_id = the patientId; Ambition fetches the result with the read-only credential you registered and checks the binding, that the inquiry was created after the patient, the template (government photo ID and selfie liveness), that the inquiry was never used for another patient, and that the verified name and date of birth match the record. `{mode: ambition}`: Ambition creates the inquiry and returns the client token for the vendor SDK you embed; poll `/current`. Your assertion of identity never counts. Identity is needed before the case enters the clinician queue.

Requires an Idempotency-Key header of 16–255 characters. Replays for 24 hours; reusing a key with a different body returns 409 rather than applying the second request.

Request body

Example response · 201

{
  "data": {
    "verificationId": "00000000-0000-4000-8000-00000000e001",
    "status": "not_started",
    "method": "byo_vendor",
    "vendor": "example-vendor",
    "synthetic": false,
    "verifiedAt": "2026-01-01T00:00:00.000Z",
    "expiresAt": "2026-01-01T00:00:00.000Z",
    "reasonCode": "example-reason-code",
    "clientToken": "example-client-token",
    "sessionUrl": "example-session-url",
    "sessionExpiresAt": "2026-01-01T00:00:00.000Z"
  },
  "meta": {
    "requestId": "example_requestId",
    "apiVersion": "example-api-version",
    "environment": "example-environment"
  }
}

Errors

The patient's identity verification state

A pending inquiry is fetched from the vendor at most every 10 seconds, so polling this settles it. Coarse reason codes only; nothing the vendor saw.

Example response · 200

{
  "data": {
    "verificationId": "00000000-0000-4000-8000-00000000e001",
    "status": "not_started",
    "method": "byo_vendor",
    "vendor": "example-vendor",
    "synthetic": false,
    "verifiedAt": "2026-01-01T00:00:00.000Z",
    "expiresAt": "2026-01-01T00:00:00.000Z",
    "reasonCode": "example-reason-code",
    "clientToken": "example-client-token",
    "sessionUrl": "example-session-url",
    "sessionExpiresAt": "2026-01-01T00:00:00.000Z"
  },
  "meta": {
    "requestId": "example_requestId",
    "apiVersion": "example-api-version",
    "environment": "example-environment"
  }
}

Errors

Can this patient be admitted to the program in a state

Reason codes only (never a clinician or licence). Also says what stands between the patient and a prescription: consent scopes, identity, an Ambition-verified contact. Headless programs serve async states at launch: a state that needs a video visit answers `modality_unavailable_headless`. California is excluded. While the program's self-serve enrollment is off (the default for the invite-only pilot) every state answers `program_self_enrollment_closed`. Nothing is written but the audit.

Request body

Example response · 200

{
  "data": {
    "programHandle": "example-program-handle",
    "state": "AL",
    "eligible": false,
    "reasonCode": "example-reason-code",
    "requiredModality": "async",
    "requiredConsentScopes": [
      "example-required-consent-scopes"
    ],
    "consentCaptureMode": "brand_rendered",
    "identityRequired": false,
    "identityVerificationMode": "byo_vendor",
    "contactVerificationRequired": false,
    "paymentRequired": false
  },
  "meta": {
    "requestId": "example_requestId",
    "apiVersion": "example-api-version",
    "environment": "example-environment"
  }
}

Errors

Admit the patient to a program

Headless admission: no launch token, no OTP. The enrollment authority rule and eligibility apply; a contact need not be verified yet (that gates the first transmission). The program's self-serve enrollment must be on, as for `POST /enrollments`. One open enrollment per program and state: a repeat returns it (200), even after the switch is turned off.

Requires an Idempotency-Key header of 16–255 characters. Replays for 24 hours; reusing a key with a different body returns 409 rather than applying the second request.

Request body

Example response · 201

{
  "data": {
    "id": "00000000-0000-4000-8000-00000000e001",
    "programHandle": "example-program-handle",
    "state": "AL",
    "status": "example-status",
    "caseId": "00000000-0000-4000-8000-00000000e001",
    "createdAt": "2026-01-01T00:00:00.000Z",
    "updatedAt": "2026-01-01T00:00:00.000Z"
  },
  "meta": {
    "requestId": "example_requestId",
    "apiVersion": "example-api-version",
    "environment": "example-environment"
  }
}

Errors

The patient's enrollments

Every enrollment of the patient in your brand, newest first, with coarse status.

Example response · 200

{
  "data": [
    {
      "id": "00000000-0000-4000-8000-00000000e001",
      "programHandle": "example-program-handle",
      "state": "AL",
      "status": "example-status",
      "caseId": "00000000-0000-4000-8000-00000000e001",
      "createdAt": "2026-01-01T00:00:00.000Z",
      "updatedAt": "2026-01-01T00:00:00.000Z"
    }
  ],
  "meta": {
    "requestId": "example_requestId",
    "apiVersion": "example-api-version",
    "environment": "example-environment"
  }
}

Errors

The patient's documents

Consent records (with the exact text accepted), care records, signed prescriptions and lab reports the clinician signed off; every document is offered as html, json and pdf. A case-bound document is listed only where your BAA covers the case. Audited. `clinical.document.available` announces each new one.

Example response · 200

{
  "data": [
    {
      "id": "example_id",
      "kind": "consent_record",
      "title": "example-title",
      "status": "example-status",
      "createdAt": "2026-01-01T00:00:00.000Z",
      "caseId": "00000000-0000-4000-8000-00000000e001",
      "formats": [
        "html"
      ]
    }
  ],
  "meta": {
    "requestId": "example_requestId",
    "apiVersion": "example-api-version",
    "environment": "example-environment"
  }
}

Errors

One document's content

`format=json` (default), `html` (escaped, no scripts) or `pdf` (rendered on request from the same minimum-necessary content, headed by your brand's mark; `Content-Disposition: attachment` with a name that is the kind of document only, never the patient's). Each read, in any format, is one audited read; never cached. A case-bound document (care record, prescription, lab report) needs your BAA with the physician group covering that case.

Query parameters

Example response · 200

{
  "data": {},
  "meta": {
    "requestId": "example_requestId",
    "apiVersion": "example-api-version",
    "environment": "example-environment"
  }
}

Errors

Export the patient's record (right of access)

The patient's copy of their record, logged as a fulfilled right-of-access request. The content is in this answer only; store it. A replay (the same Idempotency-Key) answers 201 with the same export's manifest (every field the first answer had, the same values), `content` null and `meta.replayed` true: the record is never exported twice. Cases (and their prescriptions) whose physician group your BAA does not cover are left out; the patient obtains those through the group's records request.

Requires an Idempotency-Key header of 16–255 characters. Replays for 24 hours; reusing a key with a different body returns 409 rather than applying the second request.

Example response · 201

{
  "data": {
    "id": "00000000-0000-4000-8000-00000000e001",
    "reference": "example-reference",
    "status": "example-status",
    "schema": "ambition.patient-record-export.v1",
    "generatedAt": "2026-01-01T00:00:00.000Z",
    "createdAt": "2026-01-01T00:00:00.000Z",
    "sha256": "example-sha256",
    "sections": {},
    "content": {}
  },
  "meta": {
    "requestId": "example_requestId",
    "apiVersion": "example-api-version",
    "environment": "example-environment",
    "replayed": false
  }
}

Errors

An export's manifest

The digest and section counts of an earlier export (no content).

Example response · 200

{
  "data": {
    "id": "00000000-0000-4000-8000-00000000e001",
    "reference": "example-reference",
    "status": "example-status",
    "schema": "ambition.patient-record-export.v1",
    "generatedAt": "2026-01-01T00:00:00.000Z",
    "createdAt": "2026-01-01T00:00:00.000Z",
    "sha256": "example-sha256",
    "sections": {},
    "content": {}
  },
  "meta": {
    "requestId": "example_requestId",
    "apiVersion": "example-api-version",
    "environment": "example-environment"
  }
}

Errors

Refer the patient to your medical group

Refers your patient to the medical group that covers your brand, for one program and state. On live data this is how a patient you created becomes eligible for intake. Every eligibility rule applies except the program's self-serve switch (a referral the group reviews is not self-serve). The referral waits for the group (`pending_group_review`; `clinical.referral.accepted` or `.declined` follows, `.expired` after 30 days with no decision) unless the group's written policy allows self-enrollment and the program's self-serve switch is on, when it is accepted at once (`acceptance: group_policy`). One open referral per program and state: a repeat returns it (200).

Requires an Idempotency-Key header of 16–255 characters. Replays for 24 hours; reusing a key with a different body returns 409 rather than applying the second request.

Request body

Example response · 201

{
  "data": {
    "id": "00000000-0000-4000-8000-00000000e001",
    "programHandle": "example-program-handle",
    "state": "AL",
    "status": "pending_group_review",
    "acceptance": "group_review",
    "sandboxDecision": false,
    "declineReason": "outside_group_scope",
    "externalReference": "example-external-reference",
    "enrollmentId": "00000000-0000-4000-8000-00000000e001",
    "createdAt": "2026-01-01T00:00:00.000Z",
    "updatedAt": "2026-01-01T00:00:00.000Z",
    "decidedAt": "2026-01-01T00:00:00.000Z",
    "enrolledAt": "2026-01-01T00:00:00.000Z",
    "expiresAt": "2026-01-01T00:00:00.000Z"
  },
  "meta": {
    "requestId": "example_requestId",
    "apiVersion": "example-api-version",
    "environment": "example-environment",
    "replayed": false
  }
}

Errors

The patient's referrals

Every referral of the patient in your brand, newest first. Audited.

Example response · 200

{
  "data": [
    {
      "id": "00000000-0000-4000-8000-00000000e001",
      "programHandle": "example-program-handle",
      "state": "AL",
      "status": "pending_group_review",
      "acceptance": "group_review",
      "sandboxDecision": false,
      "declineReason": "outside_group_scope",
      "externalReference": "example-external-reference",
      "enrollmentId": "00000000-0000-4000-8000-00000000e001",
      "createdAt": "2026-01-01T00:00:00.000Z",
      "updatedAt": "2026-01-01T00:00:00.000Z",
      "decidedAt": "2026-01-01T00:00:00.000Z",
      "enrolledAt": "2026-01-01T00:00:00.000Z",
      "expiresAt": "2026-01-01T00:00:00.000Z"
    }
  ],
  "meta": {
    "requestId": "example_requestId",
    "apiVersion": "example-api-version",
    "environment": "example-environment"
  }
}

Errors

One referral

One referral of the patient, as it is now (an open referral past its expiry reads `expired`). Audited.

Example response · 200

{
  "data": {
    "id": "00000000-0000-4000-8000-00000000e001",
    "programHandle": "example-program-handle",
    "state": "AL",
    "status": "pending_group_review",
    "acceptance": "group_review",
    "sandboxDecision": false,
    "declineReason": "outside_group_scope",
    "externalReference": "example-external-reference",
    "enrollmentId": "00000000-0000-4000-8000-00000000e001",
    "createdAt": "2026-01-01T00:00:00.000Z",
    "updatedAt": "2026-01-01T00:00:00.000Z",
    "decidedAt": "2026-01-01T00:00:00.000Z",
    "enrolledAt": "2026-01-01T00:00:00.000Z",
    "expiresAt": "2026-01-01T00:00:00.000Z"
  },
  "meta": {
    "requestId": "example_requestId",
    "apiVersion": "example-api-version",
    "environment": "example-environment",
    "replayed": false
  }
}

Errors

The patient accepts the referral

Call from the patient's signed-in session in your app, once the group accepted the referral, the patient accepted every consent the program requires (consent presentations and consents) and you showed the program's terms. Ambition checks the consent evidence, the terms digest and the enrollment authority again, then enrolls the patient (`status: enrolled`, `enrollmentId`): intake drafts and submissions for the program and state are accepted from then on. Identity verification is not needed here; a case without it waits in `awaiting_identity`. A repeat returns the enrolled referral.

Requires an Idempotency-Key header of 16–255 characters. Replays for 24 hours; reusing a key with a different body returns 409 rather than applying the second request.

Request body

Example response · 200

{
  "data": {
    "id": "00000000-0000-4000-8000-00000000e001",
    "programHandle": "example-program-handle",
    "state": "AL",
    "status": "pending_group_review",
    "acceptance": "group_review",
    "sandboxDecision": false,
    "declineReason": "outside_group_scope",
    "externalReference": "example-external-reference",
    "enrollmentId": "00000000-0000-4000-8000-00000000e001",
    "createdAt": "2026-01-01T00:00:00.000Z",
    "updatedAt": "2026-01-01T00:00:00.000Z",
    "decidedAt": "2026-01-01T00:00:00.000Z",
    "enrolledAt": "2026-01-01T00:00:00.000Z",
    "expiresAt": "2026-01-01T00:00:00.000Z"
  },
  "meta": {
    "requestId": "example_requestId",
    "apiVersion": "example-api-version",
    "environment": "example-environment",
    "replayed": false
  }
}

Errors

Withdraw an open referral

Closes a referral that is still waiting for the group or for the patient. A referral the patient accepted cannot be withdrawn: cancel the case instead. A repeat returns the withdrawn referral.

Requires an Idempotency-Key header of 16–255 characters. Replays for 24 hours; reusing a key with a different body returns 409 rather than applying the second request.

Example response · 200

{
  "data": {
    "id": "00000000-0000-4000-8000-00000000e001",
    "programHandle": "example-program-handle",
    "state": "AL",
    "status": "pending_group_review",
    "acceptance": "group_review",
    "sandboxDecision": false,
    "declineReason": "outside_group_scope",
    "externalReference": "example-external-reference",
    "enrollmentId": "00000000-0000-4000-8000-00000000e001",
    "createdAt": "2026-01-01T00:00:00.000Z",
    "updatedAt": "2026-01-01T00:00:00.000Z",
    "decidedAt": "2026-01-01T00:00:00.000Z",
    "enrolledAt": "2026-01-01T00:00:00.000Z",
    "expiresAt": "2026-01-01T00:00:00.000Z"
  },
  "meta": {
    "requestId": "example_requestId",
    "apiVersion": "example-api-version",
    "environment": "example-environment",
    "replayed": false
  }
}

Errors

Sandbox: the medical group accepts or declines a referral

The sandbox medical group decides a referral waiting for review, through the same decision the group's own members make (`clinical.referral.accepted` or `.declined`, livemode false; `sandboxDecision: true` on the referral). Sandbox only: a sandbox phi_server key, a synthetic brand and the developer sandbox deployment (any other answers 403 `sandbox_simulation_only`). 600 decisions per brand per hour. The same decision again answers the referral as it is.

Requires an Idempotency-Key header of 16–255 characters. Replays for 24 hours; reusing a key with a different body returns 409 rather than applying the second request.

Request body

Example response · 200

{
  "data": {
    "id": "00000000-0000-4000-8000-00000000e001",
    "programHandle": "example-program-handle",
    "state": "AL",
    "status": "pending_group_review",
    "acceptance": "group_review",
    "sandboxDecision": false,
    "declineReason": "outside_group_scope",
    "externalReference": "example-external-reference",
    "enrollmentId": "00000000-0000-4000-8000-00000000e001",
    "createdAt": "2026-01-01T00:00:00.000Z",
    "updatedAt": "2026-01-01T00:00:00.000Z",
    "decidedAt": "2026-01-01T00:00:00.000Z",
    "enrolledAt": "2026-01-01T00:00:00.000Z",
    "expiresAt": "2026-01-01T00:00:00.000Z"
  },
  "meta": {
    "requestId": "example_requestId",
    "apiVersion": "example-api-version",
    "environment": "example-environment",
    "replayed": false
  }
}

Errors

Email the patient a one-time sign-in link to your site

Emails your patient's Ambition-verified address a one-time link to a verified, attested hand-off page of your own site: `<redirectUrl>#ambition_sign_in=<signInLinkId>.<token>` (no query), sent from your brand's sender and showing only your brand's name, the link, its expiry and what to do if they did not ask. It names no program, condition or medication. The link works once, for 15 minutes, and allows 5 confirmation attempts; at most 5 links per patient in 15 minutes. The answer never carries the token or the address. Your hand-off page reads the fragment, clears it (`history.replaceState`), loads no third-party script, and posts it to your server when the patient clicks to continue (never automatically on load: a link scanner that runs scripts would spend the link); your server then calls confirmSignInLink. Takes no patient headers: the patient has not signed in to you yet. Not refused while the deployment admits no new patients: it reaches only patients who already hold an Ambition-verified email. Needs Idempotency-Key; a replay answers the same link and sends nothing.

Requires an Idempotency-Key header of 16–255 characters. Replays for 24 hours; reusing a key with a different body returns 409 rather than applying the second request.

Request body

Example response · 201

{
  "data": {
    "signInLinkId": "00000000-0000-4000-8000-00000000e001",
    "status": "sent",
    "destinationHint": "example-destination-hint",
    "expiresAt": "2026-01-01T00:00:00.000Z"
  },
  "meta": {
    "requestId": "example_requestId",
    "apiVersion": "example-api-version",
    "environment": "example-environment",
    "replayed": false
  }
}

Errors

Confirm a sign-in link's token

Your server sends the token your hand-off page read from the link's fragment. `signed_in` (once) names the patient and answers a `sessionReference`: sign them in on your side, and on the delegated calls you make for that sign-in send the reference as `Ambition-Patient-Session` with `Ambition-Patient-Auth: otp`, because the link was opened by whoever controls the patient's current Ambition-verified email (which your brand sets: this proves control of that email, not the patient's identity). Ambition accepts an otp claim only with a current session reference (24 hours, the patient's, from the key that confirmed the link, not signed out, the email not replaced since); anything else is 401 patient_sign_in_unverified. Sign out with POST /sign-in-sessions/revoke. A wrong token counts an attempt (`invalid`, with attemptsRemaining; the 5th locks the link); `used`, `expired`, `revoked` and `locked` links say so, and sign no one in. The hand-off page is checked again here: a link whose page was removed, whose site is no longer verified or whose site attestation is no longer in force is `revoked`. A link of another brand or environment is not found. Takes no patient headers. Needs Idempotency-Key; a replay answers the first confirmation's outcome and counts nothing (a signed_in replay answers the same sessionReference).

Requires an Idempotency-Key header of 16–255 characters. Replays for 24 hours; reusing a key with a different body returns 409 rather than applying the second request.

Request body

Example response · 200

{
  "data": {
    "signInLinkId": "00000000-0000-4000-8000-00000000e001",
    "status": "signed_in",
    "patientId": "00000000-0000-4000-8000-00000000e001",
    "authMethod": "otp",
    "signedInAt": "2026-01-01T00:00:00.000Z",
    "sessionReference": "example-session-reference",
    "sessionExpiresAt": "2026-01-01T00:00:00.000Z",
    "attemptsRemaining": 1
  },
  "meta": {
    "requestId": "example_requestId",
    "apiVersion": "example-api-version",
    "environment": "example-environment",
    "replayed": false
  }
}

Errors

Sign the patient out of an Ambition sign-in session

Call it when the patient signs out of your site (and whenever you end that session): the sessionReference stops backing `Ambition-Patient-Auth: otp` at once, and a replay of its confirmation answers 409 sign_in_session_not_bound instead of the reference. Revokes the session of this patient, bound by this key; another brand's, key's or patient's session, or an unknown one, is 404 sign_in_session_not_found. Signing out again answers `revoked` again. Ending access is never refused for your brand's state: it works with the PHI gate closed or the brand suspended, needing only a live phi_server key with patients.write. Takes no patient headers. Needs Idempotency-Key.

Requires an Idempotency-Key header of 16–255 characters. Replays for 24 hours; reusing a key with a different body returns 409 rather than applying the second request.

Request body

Example response · 200

{
  "data": {
    "status": "revoked"
  },
  "meta": {
    "requestId": "example_requestId",
    "apiVersion": "example-api-version",
    "environment": "example-environment",
    "replayed": false
  }
}

Errors

Issue presentation nonces for the consent documents you will show

One single-use presentation per document, bound to the patient, the document version, its text and label digests, the program, state and locale, valid 60 minutes. Refused with `hosted_consent_required` for a scope that must be captured on the hosted component, and `document_not_current` for a document that is not the current text.

Request body

Example response · 201

{
  "data": [
    {
      "presentationId": "00000000-0000-4000-8000-00000000e001",
      "documentId": "00000000-0000-4000-8000-00000000e001",
      "scope": "telehealth_consent",
      "version": 1,
      "sha256": "example-sha256",
      "labelSha256": "example-label-sha256",
      "locale": "example-locale",
      "issuedAt": "2026-01-01T00:00:00.000Z",
      "expiresAt": "2026-01-01T00:00:00.000Z"
    }
  ],
  "meta": {
    "requestId": "example_requestId",
    "apiVersion": "example-api-version",
    "environment": "example-environment"
  }
}

Errors

Record a brand-rendered consent with its render receipt

Records the patient's acceptance against its presentation: acceptedAt between issue and expiry, the receipt's text and label digests equal to the document's, the locale the presentation's, and exactly one checkbox event of the scope's own between issue and acceptance. The record is append-only, with actor provenance and how the patient authenticated to you. Emits clinical.consent.recorded.

Requires an Idempotency-Key header of 16–255 characters. Replays for 24 hours; reusing a key with a different body returns 409 rather than applying the second request.

Request body

Example response · 201

{
  "data": {
    "id": "00000000-0000-4000-8000-00000000e001",
    "scope": "example-scope",
    "status": "proposed",
    "documentId": "00000000-0000-4000-8000-00000000e001",
    "documentVersion": "example-document-version",
    "sha256": "example-sha256",
    "acceptedAt": "2026-01-01T00:00:00.000Z",
    "withdrawnAt": "2026-01-01T00:00:00.000Z",
    "withdrawsConsentId": "00000000-0000-4000-8000-00000000e001",
    "withdrawn": false,
    "channel": "example-channel",
    "actorKind": "example-actor-kind",
    "locale": "example-locale",
    "patientAction": "example-patient-action",
    "text": "example-text",
    "labelText": "example-label-text"
  },
  "meta": {
    "requestId": "example_requestId",
    "apiVersion": "example-api-version",
    "environment": "example-environment"
  }
}

Errors

The patient's consent records

Every consent record of the patient in your brand, newest first, without evidence internals. Audited.

Example response · 200

{
  "data": [
    {
      "id": "00000000-0000-4000-8000-00000000e001",
      "scope": "example-scope",
      "status": "proposed",
      "documentId": "00000000-0000-4000-8000-00000000e001",
      "documentVersion": "example-document-version",
      "sha256": "example-sha256",
      "acceptedAt": "2026-01-01T00:00:00.000Z",
      "withdrawnAt": "2026-01-01T00:00:00.000Z",
      "withdrawsConsentId": "00000000-0000-4000-8000-00000000e001",
      "withdrawn": false,
      "channel": "example-channel",
      "actorKind": "example-actor-kind",
      "locale": "example-locale",
      "patientAction": "example-patient-action",
      "text": "example-text",
      "labelText": "example-label-text"
    }
  ],
  "meta": {
    "requestId": "example_requestId",
    "apiVersion": "example-api-version",
    "environment": "example-environment"
  }
}

Errors

One consent record, with the text exactly as accepted

The record and the exact text and label the patient accepted. Audited individually.

Example response · 200

{
  "data": {
    "id": "00000000-0000-4000-8000-00000000e001",
    "scope": "example-scope",
    "status": "proposed",
    "documentId": "00000000-0000-4000-8000-00000000e001",
    "documentVersion": "example-document-version",
    "sha256": "example-sha256",
    "acceptedAt": "2026-01-01T00:00:00.000Z",
    "withdrawnAt": "2026-01-01T00:00:00.000Z",
    "withdrawsConsentId": "00000000-0000-4000-8000-00000000e001",
    "withdrawn": false,
    "channel": "example-channel",
    "actorKind": "example-actor-kind",
    "locale": "example-locale",
    "patientAction": "example-patient-action",
    "text": "example-text",
    "labelText": "example-label-text"
  },
  "meta": {
    "requestId": "example_requestId",
    "apiVersion": "example-api-version",
    "environment": "example-environment"
  }
}

Errors

Withdraw a consent

Records the withdrawal as an append-only successor record. The care team is told on every open case, and the program's consent hold answers consent_required until a new acceptance. Emits clinical.consent.withdrawn.

Requires an Idempotency-Key header of 16–255 characters. Replays for 24 hours; reusing a key with a different body returns 409 rather than applying the second request.

Request body

Example response · 200

{
  "data": {
    "id": "00000000-0000-4000-8000-00000000e001",
    "scope": "example-scope",
    "status": "proposed",
    "documentId": "00000000-0000-4000-8000-00000000e001",
    "documentVersion": "example-document-version",
    "sha256": "example-sha256",
    "acceptedAt": "2026-01-01T00:00:00.000Z",
    "withdrawnAt": "2026-01-01T00:00:00.000Z",
    "withdrawsConsentId": "00000000-0000-4000-8000-00000000e001",
    "withdrawn": false,
    "channel": "example-channel",
    "actorKind": "example-actor-kind",
    "locale": "example-locale",
    "patientAction": "example-patient-action",
    "text": "example-text",
    "labelText": "example-label-text"
  },
  "meta": {
    "requestId": "example_requestId",
    "apiVersion": "example-api-version",
    "environment": "example-environment"
  }
}

Errors

The patient's saved intake draft for a program

The saved answers as an in-progress QuestionnaireResponse, with the revision to send back. Audited.

Example response · 200

{
  "data": {
    "draftId": "00000000-0000-4000-8000-00000000e001",
    "programHandle": "example-program-handle",
    "questionnaireVersionId": "00000000-0000-4000-8000-00000000e001",
    "currentQuestionnaireVersionId": "00000000-0000-4000-8000-00000000e001",
    "state": "example-state",
    "questionnaireResponse": {
      "resourceType": "QuestionnaireResponse",
      "questionnaire": "example-questionnaire",
      "status": "in-progress",
      "item": [
        null
      ]
    },
    "currentStep": "example-current-step",
    "revision": "example-revision",
    "expiresAt": "2026-01-01T00:00:00.000Z"
  },
  "meta": {
    "requestId": "example_requestId",
    "apiVersion": "example-api-version",
    "environment": "example-environment"
  }
}

Errors

Save the patient's intake draft

Saves the in-progress answers (30-day expiry) against the current questionnaire version, for the program the path names. Send the revision you read as expectedRevision; a stale one answers 409 `conflict` and the saved draft is unchanged. A draft on an older version must be restarted first. On real data the patient needs an accepted referral or enrollment invitation for that program, as submission does, and is refused the same 422 `enrollment_required` without one.

Request body

Example response · 200

{
  "data": {
    "draftId": "00000000-0000-4000-8000-00000000e001",
    "revision": "example-revision",
    "savedAt": "2026-01-01T00:00:00.000Z"
  },
  "meta": {
    "requestId": "example_requestId",
    "apiVersion": "example-api-version",
    "environment": "example-environment"
  }
}

Errors

Restart a draft on the current questionnaire

Keeps the previous answers as read-only history and starts the draft again on the current questionnaire version. Idempotent by Idempotency-Key: a retry with the same key and body answers the first restart again (`wasDuplicate` true, the draft as it is now) and restarts nothing twice. The program binds as for saveIntakeDraft (422 `enrollment_required` on real data without an accepted invitation for it).

Requires an Idempotency-Key header of 16–255 characters. Replays for 24 hours; reusing a key with a different body returns 409 rather than applying the second request.

Request body

Example response · 200

{
  "data": {
    "draftId": "00000000-0000-4000-8000-00000000e001",
    "revision": "example-revision",
    "questionnaireVersionId": "00000000-0000-4000-8000-00000000e001",
    "state": "example-state",
    "wasDuplicate": false
  },
  "meta": {
    "requestId": "example_requestId",
    "apiVersion": "example-api-version",
    "environment": "example-environment"
  }
}

Errors

Evaluate answers: stop rules and an eligibility preview

Runs the questionnaire's stop rules over the answers so far and previews eligibility (coverage, modality, an open review, the consent hold). Only a stop is persisted (no answers); a stop clears the saved draft. Identity does not block submission: an unverified patient's case waits before the clinician queue.

Request body

Example response · 200

{
  "data": {
    "outcome": "continue",
    "eligible": false,
    "reasonCode": "example-reason-code",
    "ruleCode": "example-rule-code",
    "patientMessage": "example-patient-message",
    "requiredModality": "async",
    "flags": [
      "example-flags"
    ],
    "consentHold": "example-consent-hold",
    "identityRequiredBeforeReview": false
  },
  "meta": {
    "requestId": "example_requestId",
    "apiVersion": "example-api-version",
    "environment": "example-environment"
  }
}

Errors

Submit the intake

Submits the completed QuestionnaireResponse through Ambition's intake kernel after checking the consent hold (every required scope accepted on its current text), the questionnaire content hash, the declared location and the intake attestation. The case is created and routed to the physician group. When the patient's identity is not yet verified the case waits before the clinician queue (`caseStatus: awaiting_identity`, outstanding action identity_required) and closes after 14 days. Refusals are 422 with one of consent_required, reconsent_required, hosted_consent_required, location_mismatch, stopped, not_eligible, open_review_exists, modality_unavailable_headless, clinician_unavailable, enrollment_required, answers_incomplete or attestation_required. On real data `enrollment_required` means the patient holds no accepted referral or enrollment invitation for the program and state, the same code a draft answers for its program. Emits clinical.intake.submitted (and clinical.intake.identity_required).

Requires an Idempotency-Key header of 16–255 characters. Replays for 24 hours; reusing a key with a different body returns 409 rather than applying the second request.

Request body

Example response · 201

{
  "data": {
    "submissionId": "00000000-0000-4000-8000-00000000e001",
    "caseId": "00000000-0000-4000-8000-00000000e001",
    "programHandle": "example-program-handle",
    "questionnaireVersionId": "00000000-0000-4000-8000-00000000e001",
    "contentHash": "example-content-hash",
    "consentIds": [
      "00000000-0000-4000-8000-00000000e001"
    ],
    "declaredLocation": {
      "state": "example-state",
      "attestedAt": "2026-01-01T00:00:00.000Z"
    },
    "status": "in_review",
    "caseStatus": "awaiting_identity",
    "outstandingActions": [
      {
        "type": "identity_required",
        "requestedAt": "2026-01-01T00:00:00.000Z",
        "expiresAt": "2026-01-01T00:00:00.000Z"
      }
    ],
    "submittedAt": "2026-01-01T00:00:00.000Z",
    "wasDuplicate": false
  },
  "meta": {
    "requestId": "example_requestId",
    "apiVersion": "example-api-version",
    "environment": "example-environment"
  }
}

Errors

One intake submission and its case status

The submission's case, its coarse status and outstanding actions (identity_required while it waits). Never the answers. Needs your BAA with the physician group covering the case. Audited.

Example response · 200

{
  "data": {
    "submissionId": "00000000-0000-4000-8000-00000000e001",
    "caseId": "00000000-0000-4000-8000-00000000e001",
    "programHandle": "example-program-handle",
    "questionnaireVersionId": "00000000-0000-4000-8000-00000000e001",
    "contentHash": "example-content-hash",
    "consentIds": [
      "00000000-0000-4000-8000-00000000e001"
    ],
    "declaredLocation": {
      "state": "example-state",
      "attestedAt": "2026-01-01T00:00:00.000Z"
    },
    "status": "in_review",
    "caseStatus": "awaiting_identity",
    "outstandingActions": [
      {
        "type": "identity_required",
        "requestedAt": "2026-01-01T00:00:00.000Z",
        "expiresAt": "2026-01-01T00:00:00.000Z"
      }
    ],
    "submittedAt": "2026-01-01T00:00:00.000Z",
    "wasDuplicate": false
  },
  "meta": {
    "requestId": "example_requestId",
    "apiVersion": "example-api-version",
    "environment": "example-environment"
  }
}

Errors

Report a side effect or a product problem

Files the patient's report after you showed the current safety screen (echo its version). A serious answer makes it urgent for the clinical safety team; a report on a compounded or interim-policy product is routed to the prescriber, the dispensing pharmacy and the MedWatch path. Emits clinical.safety_report.received.

Requires an Idempotency-Key header of 16–255 characters. Replays for 24 hours; reusing a key with a different body returns 409 rather than applying the second request.

Request body

Example response · 201

{
  "data": {
    "id": "00000000-0000-4000-8000-00000000e001",
    "reference": "example-reference",
    "status": "example-status",
    "seriousness": "example-seriousness",
    "caseId": "00000000-0000-4000-8000-00000000e001",
    "category": "example-category",
    "routedToPhysicianGroup": false,
    "wasDuplicate": false
  },
  "meta": {
    "requestId": "example_requestId",
    "apiVersion": "example-api-version",
    "environment": "example-environment"
  }
}

Errors

The patient's safety reports

Reference, category, status and date of each report. Never the assessment or decision. Audited.

Example response · 200

{
  "data": [
    {
      "id": "00000000-0000-4000-8000-00000000e001",
      "reference": "example-reference",
      "category": "example-category",
      "status": "example-status",
      "submittedAt": "2026-01-01T00:00:00.000Z"
    }
  ],
  "meta": {
    "requestId": "example_requestId",
    "apiVersion": "example-api-version",
    "environment": "example-environment"
  }
}

Errors

Request this cycle's fill of a prescription

Call once per billing cycle of your subscription, after you charge the patient. Ambition checks the prescription's clinical currency (approval expiry, refills left, check-ins and monitoring labs due), the declared location, regulatory standing and your fulfillment release, then either creates the refill's pharmacy order (`status: requested`; `clinical.fill.requested`, then `clinical.fill.transmitted` when the pharmacy has it) or holds the fill with one coarse `holdReason` (`clinical.fill.held`). Idempotent per `cycleRef`: the same cycleRef answers the same fill, and repeating it re-evaluates a held fill, so retry a hold with the same cycleRef once it clears. A new cycleRef supersedes an earlier held fill. The first dispense of a new prescription is its own order (sent on signing, or on your release under brand_release); call this for each later cycle. To pause or cancel, do not request a fill; to stop therapy, send a renewal request with `requestedChange: stop` or a message to the care team. When the last authorized refill is used, `clinical.prescription.refills_exhausted` tells you to offer a renewal.

Requires an Idempotency-Key header of 16–255 characters. Replays for 24 hours; reusing a key with a different body returns 409 rather than applying the second request.

Request body

Example response · 201

{
  "data": {
    "id": "00000000-0000-4000-8000-00000000e001",
    "prescriptionId": "00000000-0000-4000-8000-00000000e001",
    "cycleRef": "example-cycle-ref",
    "status": "held",
    "holdReason": "prescription_expired",
    "fillNumber": 1,
    "orderId": "example_orderId",
    "declaredState": "AL",
    "requestedAt": "2026-01-01T00:00:00.000Z",
    "evaluatedAt": "2026-01-01T00:00:00.000Z",
    "refillsRemaining": 1
  },
  "meta": {
    "requestId": "example_requestId",
    "apiVersion": "example-api-version",
    "environment": "example-environment",
    "replayed": false
  }
}

Errors

List a prescription's fills

The fills you requested for one of the patient's prescriptions, newest first: status, coarse hold reason, fill number and order id. No address, product or clinical field.

Example response · 200

{
  "data": [
    {
      "id": "00000000-0000-4000-8000-00000000e001",
      "prescriptionId": "00000000-0000-4000-8000-00000000e001",
      "cycleRef": "example-cycle-ref",
      "status": "held",
      "holdReason": "prescription_expired",
      "fillNumber": 1,
      "orderId": "example_orderId",
      "declaredState": "AL",
      "requestedAt": "2026-01-01T00:00:00.000Z",
      "evaluatedAt": "2026-01-01T00:00:00.000Z",
      "transmittedAt": "2026-01-01T00:00:00.000Z",
      "closedAt": "2026-01-01T00:00:00.000Z"
    }
  ],
  "meta": {
    "requestId": "example_requestId",
    "apiVersion": "example-api-version",
    "environment": "example-environment"
  }
}

Errors