CareAtlas Integration Guide

Overview

This guide describes how to implement order submission using only the HaaS APIs, with no dependency on the provider-portal UI. It is intended for developers building headless or custom integrations (e.g. external provider portals, scripts, or server-to-server flows) that need to create orders in the same way as this app.

API contract: HTTP paths below match [public/specs/CareAtlas-Unified-API-oas3-v0.1.json](../public/specs/CareAtlas-Unified-API-oas3-v0.1.json) (CareAtlas Unified API). Combine them with the API base URL (e.g. staging https://qa.api.thecareatlas.com). Hub webhook routes are documented in §8 Webhooks (Hub API). To re-check that guide paths still exist in that spec, run python3 scripts/verify-careatlas-guide-paths.py from the repo root.

Goal: From a provider/tenant context, get to a successfully submitted order (prescription-based flow.

1. 1. Getting started

1.1 High-level flow (registration → screening → consult → prescription → order)

The app’s provider-portal flow is:

1. Tenant & auth – Resolve tenant ID and partner app ID (Fetch Tenant ID and Partner App ID); ensure all requests use the same tenant and Bearer token.
2. Patient – Ensure the patient exists and has account.id (for customer.accountId) and a valid address (required for order import).
3. Clinic – Ensure the clinic exists (or create/link) and you have clinic details (name, address, email, phone) required for OrderImportRequest.clinic (ClinicInfo).
4. Practitioner – Ensure the practitioner exists and you have practitionerId for consults, prescriptions, and order context as needed. Note: Practitioner registration requires a valid NPI verifiable from NPPES NPI Registry.
5. Product / variant – Resolve productVariantId from the catalog if not already on the prescription. Product Variant is the actual medication that will be ordered.
6. Screening – Complete the questionnaire session and obtain screeningSessionId (§4 Patient Screening).
7. Consult (when your tenant requires it) – Create and drive a consult tied to that screening session, patient, practitioner, and product (§5 Consult). Skip if you prescribe directly after screening.
8. Prescription – Create (or find) a prescription with productId and productVariantId via POST /clinical/v1/prescriptions/create, or use GET /clinical/v1/prescriptions/search for an existing record (§6 Step 2).
9. Order import – Build OrderImportRequest and call POST /commerce/v1/orders/import (§7 Creating Orders).

For outbound webhooks (register your HTTPS URL, signing secret, test and retry deliveries), see §8 Webhooks (Hub API). For a compact endpoint index across services, see §9 API Reference.

2. 2. Access & Authentication

• API base URL – Staging: https://qa.api.thecareatlas.com Production: https://api.thecareatlas.com
• Authentication – Once you receive your App Client credentials from the CareAtlas team, you can request auth token from AWS Cognito: https://qa.app-auth.thecareatlas.com using the credentials. You need a valid Bearer access token with the following scopes per API:
  • Identity (/identity/v1/* on the API base URL) – api://haas.identity/haas.api.read, api://haas.identity/haas.api.write
  • Catalog (/catalog/v1/*) – api://haas.catalog/haas.api.read, api://haas.catalog/haas.api.write
  • Clinical (/clinical/v1/*) – api://haas.clinical/haas.api.read,api://haas.clinical/haas.api.write
  • Commerce (/commerce/v1/*) – api://haas.commerce/haas.api.read,api://haas.commerce/haas.api.write
  • Screening (/screening/v1/*) – api://haas.screening/haas.api.read, api://haas.screening/haas.api.write (as required by each operation in the spec)
  • Consult (/consult/v1/*) – api://haas.consult/haas.api.read, api://haas.consult/haas.api.write (as required by each operation in the spec; see §5 Consult)
  • Hub (/hub/v1/*) – api://haas.hub/haas.api.read, api://haas.hub/haas.api.write for webhook subscriptions, deliveries, and related operations (see §8).
• Tenant context – X-Tenant-Id header is required on Hub subscription and delivery calls (and most other tenant-scoped routes). You obtain it from GET /identity/v1/tenants/me (see Fetch Tenant ID and Partner App ID). GET /hub/v1/webhooks/event-types/search has no tenant header in the bundled OpenAPI—confirm with your deployment if the gateway differs.

Fetch Tenant ID and Partner App ID

Endpoint: GET /identity/v1/tenants/me (getMyTenants)
Headers: Authorization: Bearer <access_token>

Response type: MyTenantsResponse — partnerApp may be null when the caller has no linked partner application.

What to use:

Sample response:

3. 3. Patient Registration

Prerequisites — registration

Complete §2 Access & Authentication — Bearer token, Identity read/write scopes, and X-Tenant-Id from Fetch Tenant ID and Partner App ID.

Register or resolve the patient in Identity so you have a patientId (UUID) for screening (POST /screening/v1/sessions/create), prescriptions, and orders.

Endpoint: POST /identity/v1/patients/resolve-by-email
Headers: Authorization: Bearer <token>, X-Tenant-Id: <tenantId>, Content-Type: application/json

The API resolves an existing patient by email in the tenant or creates one when none exists. Use patient.id from the response as patientId in later steps.

Request body: PatientResolveRequest

The sample below sets gender to "Female" (use "Male" for male patients).

Sample request (POST /identity/v1/patients/resolve-by-email):

Response: PatientResolveResponse — the nested patient object is a PatientResponse.

Sample response:

Lookup by id or email (GET /identity/v1/patients/search)

When you need to find or verify a patient by id, email, or accountId (instead of or after resolve-by-email) above, use search.

Endpoint: GET /identity/v1/patients/search
Headers: Authorization: Bearer <token>, X-Tenant-Id: <tenantId>

Query parameters: Pass the patient’s id (and/or email, accountId, etc. per spec) to retrieve a paged list. When filtering by unique id, use the matching row from data.

Response: PagedResponseOfPatientResponse — each element in data is a PatientResponse.

For order import you need:

• patient.id → customer.patientId
• patient.account.id → customer.accountId (required; resolve from profile/session if not on patient in your flow)
• patient.address → must be a full Address object with at least:
  • addressLine1, addressLine2, city, state, zipCode, phone

If the patient has no address or no account.id, create or update the patient via the appropriate Identity APIs before calling order import.

Sample response (GET /identity/v1/patients/search?id=01933a7e-7b2c-7456-8000-000000000010&limit=1): Example shape for data[0]:

4. 4. Patient Screening

Before prescribing, many flows require the patient to complete a screening questionnaire tied to a medication (catalog product + variant). A typical headless sequence matches the provider portal: choose the product/variant and questionnaire, then start a screening session. Subsequent calls (answer questions, consent, submit) use the session id returned here.

Prerequisites — screening

Complete these before Step 1: Select medication:

• §3 Patient Registration — Prerequisites — registration, resolve-by-email, optional Lookup by id or email (GET /identity/v1/patients/search); you need patientId for CreateSessionRequest.
• Screening routes — Confirm Screening scopes on your Bearer token (§2 Access & Authentication) for /screening/v1/*.

---

Step 1: Select medication

A screening session is bound to a catalog product (productId), a product variant (productVariantId), and a questionnaire (questionnaireId). Resolve the product first (to pick a variant), then load active questionnaires and pick questionnaireId for your care path (use the bundle endpoint when you need full question/option payloads for the UI).

---

2.1 Search catalogs

Source: GET /catalog/v1/catalogs/search (searchCatalogs). Lists catalogs available to the tenant (each catalog groups products). Use this when you need catalogId to scope Search products (§2.2) or to show a catalog picker in the UI.

Endpoint: GET /catalog/v1/catalogs/search
Headers: Authorization: Bearer <token>; X-Tenant-Id (required — current clinic/tenant UUID); optional If-None-Match

Query parameters (all optional unless noted)

(Query parameters are optional; omit If-None-Match on first call.)

Sample response (200) — PagedResponseOfCatalogSearchResponse:

Use data[].id as catalogId when calling GET /catalog/v1/products/search. If includeCategories is omitted or unsupported, categories may be an empty array.

Errors: 401, 403, 404 (per spec). 304 when If-None-Match matches.

Note: Skip this step if catalogId is already known (config, or from product.catalog.id on a product returned by search).

---

2.2 Get product and variant

Source: GET /catalog/v1/products/search (searchProducts) and optionally GET /catalog/v1/products/{id}/find (findProductById). Prefer search—many deployments only expose /products/search; /find can be absent on the gateway even when it appears in the spec. Catalog calls require X-Tenant-Id on the request headers.

Search products (recommended)

Endpoint: GET /catalog/v1/products/search
Headers: Authorization: Bearer <token> (catalog may use a separate client or token); X-Tenant-Id (tenant UUID); optional If-None-Match

Query parameters (all optional; combine per your catalog)

Request: No body.

Response: 200 — PagedResponseOfProductResponse. Use data[].id as productId. Choose productVariantId from data[].variants[] (match the variant you need).

Sample request

(The catalogId query parameter is optional; use it to scope to a catalog from §2.1.)

Sample response (200) — full page body (example GET /catalog/v1/products/search?variantId=01933a7e-7b2c-7456-8000-000000000031&limit=5):

Get product by id (optional)

Endpoint: GET /catalog/v1/products/{id}/find — **operationId:** findProductById` in the same OpenAPI file (path key /catalog/v1/products/{id}/find). Headers: Authorization; X-Tenant-Id (required). Returns a single ProductResponse (same inner shape as data[] from search). If this route is not routed by your API gateway, use Search products with variantId or name / sku instead.

Request: No body.

Sample request

Sample response (200) — one ProductResponse (not wrapped in data); same fields as a single element of data[] in Search products:

---

2.3 Fetch Available Questionnaires

The unified API exposes GET /screening/v1/questionnaires/active (not a separate paged /questionnaires list). Use it to discover questionnaireId. For rendering or validating the flow, load the full bundle with GET /screening/v1/questionnaires/{id}/bundle.

List active questionnaires

Endpoint: GET /screening/v1/questionnaires/active
Headers: Authorization: Bearer <token>; optional If-None-Match

Query parameters

Request: No body.

Response: 200 — JSON array of QuestionnaireResponse. Use [].id as questionnaireId for POST /screening/v1/sessions/create.

Sample response (GET /screening/v1/questionnaires/active?name=branded):

Get questionnaire bundle (optional)

Endpoint: GET /screening/v1/questionnaires/{id}/bundle
Headers: Authorization: Bearer <token>; optional If-None-Match

Path parameters

Query parameters

Response: 200 — QuestionnaireBundleResponse (questions, answer options, and related fields per spec—use this to drive the screening UI after you create a session).

Note: Carry forward productId, productVariantId (from 2.2), and questionnaireId (from 2.3) into Step 3.

---

Step 2: Create screening session

Endpoint: POST /screening/v1/sessions/create (operationId: createSession)
Headers: Authorization: Bearer <token>, X-Tenant-Id: <tenantId>, Content-Type: application/json

Body: CreateSessionRequest — all fields are required per the OpenAPI schema:

Response: 201 with SessionCreateResponse, including id (session id). Use that value as {id} in Step 3 to post answers and complete the session.

Notes:

• 409 may indicate an existing session for the same patient/questionnaire — follow your product rules (resume vs. new session).
• Confirm with CareAtlas that your client’s Bearer token includes Screening / CRUD write scopes for /screening/v1/* routes (gateway requirements may differ from Identity or Clinical alone).

---

Step 3: Submit questionnaire answers and complete the session

After POST /screening/v1/sessions/create returns a session id, drive the questionnaire with the Screening API: optionally fetch batches of questions, send answers, record consent when your flow requires it, then submit the session so downstream steps (e.g. prescriptions tied to screeningSessionId when your deployment supports that) can proceed.

Headers (all calls below): Authorization: Bearer <token>, X-Tenant-Id: <tenantId>, and Content-Type: application/json on POST bodies.

3.1 Get the next question batch (optional)

Endpoint: GET /screening/v1/sessions/{id}/next
Path: {id} = session id from Step 3.

Query parameters: optional limit (string per client), optional If-None-Match.

Response: 200 — QuestionnaireNextResponse:

Use this in paged UIs: call /next, render questions, collect answers, then POST /answer (§4.2). Repeat until isLastBatch is true or you have collected every answer your bundle requires.

Alternative: If you already loaded GET /screening/v1/questionnaires/{id}/bundle (§2.3), you can build the full form without calling /next, then send one or more /answer requests with every linkId the bundle defines.

3.2 Post answers

Endpoint: POST /screening/v1/sessions/{id}/answer
Body: AnswerBundleRequest — { "answers": [ ... ] }

Each AnswerItem typically includes:

Sample request (POST /screening/v1/sessions/{id}/answer):

Response: 200 — AnswerBundleResponse (per spec). You may call /answer multiple times (e.g. per batch) before submitting.

3.3 Record consent (when required)

Some tenants require consent before final submit. If your bundle or product rules say consent is needed:

Endpoint: POST /screening/v1/sessions/{id}/consent
Body: CreateConsentRequest — e.g. scope, termsVersion, grantedAt / expiresAt (ISO date-times) per OpenAPI.

Skip this step if your integration does not use session-level consent.

3.4 Submit the session

When all required answers are saved, complete the session:

Endpoint: POST /screening/v1/sessions/{id}/submit
Body: SessionSubmitRequest

Sample request:

Response: 200 — SubmitSessionResponse — may include status, completedAt, and recommendedProductVariants (used by clinical flows to suggest variants). Use the same sessionId as screeningSessionId on POST /consult/v1/consults/create (§5 Step 2) when your flow includes a consult. For prescribing, pass the consult id as consultId on POST /clinical/v1/prescriptions/create (§6 Step 2).

Operational notes

• Order of operations (typical): create session → (/next + /answer)* → optional /consent → /submit. Exact branching depends on questionnaire configuration.
• Idempotency: Re-posting overlapping answers may be rejected or merged per backend rules; prefer one bundle per batch or a single final bundle before submit.
• Errors: 400 validation (missing required answers), 404 unknown session id — confirm session id and tenant.

5. 5. Consult

Many tenant programs run a consult (provider visit or chat thread) after screening and before prescribing. Consult records tie together patient, practitioner, screening session, and catalog product / variant via POST /consult/v1/consults/create (CreateConsultRequest). Skip this section if your flow prescribes directly from screening without a separate consult step.

Prerequisites — consult

• §4 Prerequisites — screening — Completed screening; you need screeningSessionId from §4 Step 3.
• §3 Patient Registration — patientId.
• §2 Access & Authentication — Bearer token with Consult scopes (api://haas.consult/haas.api.read, api://haas.consult/haas.api.write).
• Practitioner — practitionerId for CreateConsultRequest (resolve with Identity search/onboard; see §6 Prerequisites — prescriptions under Ensure Practitioner exists).
• Product / variant — selectedProductId and selectedProductVariantId aligned with screening / catalog (§4 Step 1).

Step 1: List consults (optional)

Endpoint: GET /consult/v1/consults/search (operationId: searchConsults)
Headers: Authorization: Bearer <token>, X-Tenant-Id (required)

Query (typical): patientId, practitionerId, status, screeningSessionId, selectedProductId, selectedProductVariantId, limit, next, sortBy, sortOrder

Response: 200 — PagedResponseOfGetConsultSummaryResponse — use to find or resume consults for a patient or session context.

Sample response (200) — shape of data[0] when listing:

(Metadata keys may match PageMetadata in your client; confirm against the spec.)

Step 2: Create a consult

Endpoint: POST /consult/v1/consults/create (createConsult)
Headers: Authorization: Bearer <token>, X-Tenant-Id, Content-Type: application/json

Body: CreateConsultRequest — required per OpenAPI: patientId, practitionerId, topic, channel, screeningSessionId, selectedProductId, selectedProductVariantId.

Sample request (POST /consult/v1/consults/create):

Response: 200 — CreateConsultResponse — includes id (consult uuid). Use this id on GET/messages routes below.

Sample response (200):

Step 3: Get consult detail

Endpoint: GET /consult/v1/consults/{id}/get (getConsult)
Headers: Authorization: Bearer <token>, X-Tenant-Id; optional If-None-Match

Response: 200 — GetConsultResponse — status, screeningSessionId, patientId, practitionerId, selected product ids, conversationRef, participants, chats, lifecycle timestamps, etag.

Sample response (200) — GetConsultResponse for path {id} (same consult id as create response):

Step 4: Messages and integrations

Beluga inbound webhooks (POST /consult/v1/consult/message, /consult/v1/consult/cs-message, /consult/v1/consult/close, /consult/v1/consult/cancel) are not in the unified partner OpenAPI; they are server-to-server integration routes on the consult service.

Step 5: Close or cancel consult (provider / tenant API)

Close marks the consult ended (e.g. provider portal after prescription create). Cancel records cancellation with canceledAtUtc and canceledBy.

When your workflow is ready to prescribe, continue to §6 Creating Prescriptions.

6. 6. Creating Prescriptions

Prerequisites — prescriptions

Build on §4 Prerequisites — screening (patient, screening session workflow, Screening scopes). If your program runs a provider consult after screening, complete §5 Prerequisites — consult first. For Identity patient fields used on orders, follow §3 Patient Registration and Lookup by id or email (GET /identity/v1/patients/search) when needed.

This section adds clinic and practitioner prerequisites not covered above:

Ensure Clinic exists

Order import requires clinic (ClinicInfo) on every OrderImportRequest—clinic name, full address, email, and phone. Use the clinic APIs to find an existing clinic or create/link one, then map the result to ClinicInfo for the order.

Search clinics

Endpoint: GET /identity/v1/tenants/clinics/search
Headers: Authorization: Bearer <token>, X-Tenant-Id: <tenantId>

Query parameters: name, id, npi, externalId, limit, after (optional). Use these to find a clinic by name, tenant id, NPI, or external id.

Response: Paged list of tenants (clinics). Each item is a TenantResponse-like object with id, name, partnerId, parentTenantId, role, and attributes. Use the tenant(s) to build or resolve ClinicInfo for the order (name, address, email, phone—from tenant attributes or your own data).

Sample response (GET /identity/v1/tenants/clinics/search): Returns a paged list; each element in data has id, name, partnerId, parentTenantId, role, etag, and related fields. Map to ClinicInfo using the tenant’s name and attribute/address data as required by your backend.

Onboard clinic

Endpoint: POST /identity/v1/tenants/clinics/onboard
Headers: Authorization: Bearer <token>, X-Tenant-Id: <tenantId>, Content-Type: application/json

Body: OnboardClinicRequest — partnerId, parentTenantId, name, and attributes (e.g. name, npi, addressId, email, phone, description). See Object reference for schema details.

Response: 201 with TenantResponse. Use the returned tenant (and any address resolved from attributes.addressId) to build ClinicInfo for order import.

Sample request (POST /identity/v1/tenants/clinics/onboard):

Sample response (POST /identity/v1/tenants/clinics/onboard): Returns the created/linked tenant with id, name, partnerId, parentTenantId, role, etag, and timestamps. Use this tenant and your address data to populate OrderImportRequest.clinic (ClinicInfo).

What you need for OrderImportRequest:

• clinic – ClinicInfo: clinicName, clinicAddressLine1, clinicAddressLine2, clinicCity, clinicState, clinicZip, clinicEmail, clinicPhoneNumber. Populate from the clinic/tenant returned by search or onboard, and from the resolved address when using attributes.addressId.

---

Ensure Practitioner exists

You need practitioner.id as practitionerId in CreatePrescriptionCommandRequest when creating prescriptions (Step 2); it is optional in the OpenAPI schema but typically required for your workflow.

Fetching existing practitioner

If you already have a practitioner ID (e.g. from your system or a previous onboard response), call GET /identity/v1/practitioners/search with query id=<practitionerId> (and/or npi, email, etc. per spec).

Headers: Authorization: Bearer <token>; optional If-None-Match

Response: PagedResponseOfPractitionerResponse — use the matching PractitionerResponse from data (see PractitionerResponse).

Sample response (GET /identity/v1/practitioners/search?id=01933a7e-ae5f-7789-8000-000000000021&limit=1): Example shape for data[0]:

Creating new practitioner

If the practitioner does not exist, use POST /identity/v1/practitioners/onboard with PractitionerOnboardRequest (see Object reference for schema). The API returns an existing practitioner when one matches (e.g. by NPI/tenant), or creates one. Use the returned practitioner.id as practitionerId in prescription and order flows.

Headers: Authorization: Bearer <token>, X-Tenant-Id: <tenantId>, Content-Type: application/json

Body: PractitionerOnboardRequest — see Object reference for schema.

Sample request (POST /identity/v1/practitioners/onboard):

Sample response (POST /identity/v1/practitioners/onboard):

---

Step 1: Resolve Product Variant (Medication)

Endpoint: GET /catalog/v1/products/search (e.g. query variantId from the prescription, or name / sku) — see §4 Step 2.2. Optional: GET /catalog/v1/products/{id}/find when your gateway exposes it (same ProductResponse shape; send X-Tenant-Id).

Headers: Authorization (catalog may use a different token in some environments); X-Tenant-Id; optional If-None-Match

Response: ProductResponse (from data[] or from /find) — use the product’s variants to get productVariantId (from prescription or e.g. variants[0].id).

The Import Order API also requires uomId (unit of measure) on each line. This app does not use UOM for any business logic; it only sends it because the API requires it. The app gets uomId from the variant when present, otherwise uses a fixed default. For headless implementations: send the variant’s uomId if available, or a known default UUID your backend accepts.

Sample response (single ProductResponse — e.g. one data row from search, or body of /find when available):

(Schema may vary; the important fields for order import are variants[].id (productVariantId) and variants[].uomId.)

---

Step 2: Get or create a prescription

Clinical routes in CareAtlas-Unified-API-oas3-v0.1.json include GET /clinical/v1/prescriptions/search, POST /clinical/v1/prescriptions/create, GET /clinical/v1/prescriptions/{id}/validate, and PATCH /clinical/v1/prescriptions/{id}/update. For provider prescribing after a consult, use create with consultId from §5 Step 2 (and pharmacyId, medsPrescribed, practitioner fields per your workflow).

Search existing prescriptions

Endpoint: GET /clinical/v1/prescriptions/search with query id=<prescriptionId> (and/or patientId, patientEmail, etc. per spec).
Headers: X-Tenant-Id, Authorization

Response: PagedResponseOfPrescriptionResponse — use the matching PrescriptionResponse from data.

Create prescriptions (provider flow)

Endpoint: POST /clinical/v1/prescriptions/create (operationId: createPrescriptionCommand)
Headers: X-Tenant-Id, Authorization, Content-Type: application/json

Body: CreatePrescriptionCommandRequest; each element of medsPrescribed is a MedPrescribedInternal. See Object reference for fields.

Response: 201 Created — JSON array of PrescriptionResponse (one entry per item in medsPrescribed).

Sample request:

Sample response (201): Same shape as each element in the search data array below (array of PrescriptionResponse).

Validate a prescription

Endpoint: GET /clinical/v1/prescriptions/{id}/validate (operationId: validatePrescription)
Headers: X-Tenant-Id, Authorization

Response: 200 — ValidatePrescriptionResponse (see ValidatePrescriptionResponse): includes isValid (boolean).

Update a prescription

Endpoint: PATCH /clinical/v1/prescriptions/{id}/update (operationId: updatePrescriptionCommand)
Headers: X-Tenant-Id, Authorization, Content-Type: application/json

Body: UpdatePrescriptionCommandRequest — all properties optional in the bundled schema; use for notes, approval metadata, or payment fields per your process.

Response: 200 — PrescriptionResponse.

Sample response (GET /clinical/v1/prescriptions/search?id=01933a7e-9d4e-7678-8000-000000000020&limit=1): Example shape for data[0]:

Step 3: Map prescription fields for order import

From the prescription you need for the order:

• id → lines[].matchedPrescriptionId
• patientId → customer.patientId
• productId → lines[].productId
• productVariantId → lines[].productVariantId (or resolve from product in Step 1)
• quantityAuthorized → lines[].qty (e.g. quantityAuthorized.value or default 1)

---

7. 7. Creating Orders

Prerequisites — orders

Build on §6 Prerequisites — prescriptions (clinic, practitioner, product variant, and prescription). Confirm §2 Access & Authentication grants Commerce scopes for POST /commerce/v1/orders/import (same Bearer token and X-Tenant-Id as earlier steps).

Complete §6 Step 3 so you have the prescription and patient field mapping before assembling the payload. Full request shape and the import call are in Build OrderImportRequest and call Import Order below.

Build OrderImportRequest and call Import Order

Build the request body and call the import endpoint. Body schema: OrderImportRequest — see Object reference for full schema and nested types (CustomerInfo, ClinicInfo, LineInfo, Address, TotalsInfo, PaymentInfo, SourceInfo).

Mapping from prescription to order: Use the data from earlier steps to fill the payload:

• prescription.id → lines[].matchedPrescriptionId
• prescription.patientId → customer.patientId
• prescription.productId → lines[].productId
• prescription.productVariantId → lines[].productVariantId (or from §6 Step 1)
• prescription.quantityAuthorized → lines[].qty (e.g. .value or default 1)
• patient.account.id → customer.accountId (§3 / lookup)
• patient.address → shippingAddress and billingAddress (full Address objects)
• clinic → §6 Prerequisites — prescriptions (Ensure Clinic exists); source.partnerAppId from Fetch Tenant ID and Partner App ID

Numeric fields like qty, unitPrice, lineTotal, and totals may be strings in the API; see the sample request below and OrderImportRequest.

Endpoint: POST /commerce/v1/orders/import Headers: Authorization: Bearer <token>, X-Tenant-Id: <tenantId>, Content-Type: application/json. Optional: Idempotency-Key: <key> to avoid duplicate orders on retries.

Sample request (POST /commerce/v1/orders/import):

Sample response (201 Created):

8. 8. Working with Webhooks

The Hub service manages outbound webhooks: CareAtlas POSTs event payloads to your HTTPS URL when something happens (per event type). You do not implement CRUD against arbitrary domain tables here—you configure subscriptions, verify delivery to your endpoint, and operate retries and secrets. All Hub webhook routes use the same API base URL as the rest of the unified API; paths published in CareAtlas-Unified-API-oas3-v0.1.json appear in the §9 API Reference table.

The bundled spec includes subscription create, patch update, disable, plus search, get (…/get), deliveries, test, retry, and rotate-secret.

OpenAPI: Examples include createSubscriptionCommand, updateSubscriptionCommand, disableSubscriptionCommand, listEventTypesQuery, listSubscriptionsQuery, getSubscriptionQuery, listSubscriptionsForEventType, testWebhook, getDeliveryQuery, retryDelivery, rotateSecret — verify names in the spec.

Getting started

Available event types (reference)

Display name (left) is for readability; the name string (right) matches event-type identifiers. The authoritative list—including payloadSchema—comes from GET /hub/v1/webhooks/event-types/search (List event types).

Your inbound endpoint

Configure your server to accept HTTPS POST from CareAtlas, respond with 2xx quickly, and verify signatures using the signingSecret from Create subscription (201) or Rotate signing secret. Exact headers and body envelope follow your deployment’s webhook contract (payload shapes are described per EventTypeResponse.payloadSchema where provided).

Authentication and headers

• Bearer token must include Hub scopes: api://haas.hub/haas.api.read (event types and subscription reads) and api://haas.hub/haas.api.write (create, update, and disable subscription; test delivery; retry delivery; rotate secret).
• X-Tenant-Id – Required on routes that declare it (e.g. POST /hub/v1/webhooks/subscriptions/create, GET /hub/v1/webhooks/subscriptions/search, GET /hub/v1/webhooks/subscriptions/{id}/deliveries). GET /hub/v1/webhooks/event-types/search has no tenant header in the bundled OpenAPI.

List event types

Endpoint: GET /hub/v1/webhooks/event-types/search (listEventTypesQuery)
Headers: Authorization: Bearer <token> (Hub read scope).

Response

Subscriptions

Create a subscription

Endpoint: POST /hub/v1/webhooks/subscriptions/create (createSubscriptionCommand)
Headers: Authorization: Bearer <token>, X-Tenant-Id: <tenantId>, Content-Type: application/json

Body: CreateSubscriptionRequest — required: url, eventTypes (array of event name strings from List event types), description, expiresAtUtc. Optional: notificationEmails (comma-separated or deployment-specific format for alert recipients).

Response: 201 Created — CreateSubscriptionResponse includes id, url, eventTypes, signingSecret, expiresAtUtc, notificationEmails, etag, isActive, partnerAppId, etc. Store signingSecret securely; it is used to verify inbound webhook requests (also returned only at rotate-secret thereafter).

Search subscriptions

Endpoint: GET /hub/v1/webhooks/subscriptions/search (listSubscriptionsQuery)
Headers: Authorization: Bearer <token>, X-Tenant-Id: <tenantId>

Query (typical): limit, next, sortBy, sortOrder (per OpenAPI).

Get one subscription

Endpoint: GET /hub/v1/webhooks/subscriptions/{id}/get (getSubscriptionQuery)
Headers: Authorization: Bearer <token>, X-Tenant-Id: <tenantId>; optional If-None-Match

Search subscriptions for an event type

Endpoint: GET /hub/v1/webhooks/event-types/{name}/subscriptions/search (listSubscriptionsForEventType)
Headers: Authorization: Bearer <token>, X-Tenant-Id: <tenantId>

Path {name} is the event type name (e.g. order.created).

Update a subscription

Endpoint: PATCH /hub/v1/webhooks/subscriptions/{id}/update (updateSubscriptionCommand)
Headers: Authorization: Bearer <token>, X-Tenant-Id: <tenantId>, Content-Type: application/json

Body: JSON body per the OpenAPI PATCH operation (the bundled file may reference a placeholder schema name; your generated client maps it to the subscription update type). May include notificationEmails when updating alert recipients. 200 returns UpdateSubscriptionResponse (id, url, eventTypes, notificationEmails, expiresAtUtc, etag, etc.—no signingSecret). Responses may include 412 / 409 for concurrency or conflict—follow etag / conditional request rules in the spec for your client.

Disable a subscription

Endpoint: POST /hub/v1/webhooks/subscriptions/{id}/disable (disableSubscriptionCommand)
Headers: Authorization: Bearer <token>, X-Tenant-Id: <tenantId>

Response: 204 No Content — stops deliveries for that subscription (per API semantics; confirm behavior with your deployment).

Test delivery

Endpoint: POST /hub/v1/webhooks/subscriptions/{id}/test
Headers: Authorization: Bearer <token>, X-Tenant-Id: <tenantId>

Triggers a test delivery to the subscription URL. Response: 202 Accepted. Use after creating (or otherwise obtaining) a subscription to confirm connectivity before production traffic.

Rotate signing secret

Endpoint: POST /hub/v1/webhooks/subscriptions/{id}/rotate-secret
Headers: Authorization: Bearer <token>, X-Tenant-Id: <tenantId>

Returns a new secret (response shape per RotateSecretResponse in the OpenAPI spec). Update your verifier to accept both old and new secrets during rotation, then retire the old secret.

Deliveries

List deliveries for a subscription

Endpoint: GET /hub/v1/webhooks/subscriptions/{id}/deliveries
Headers: Authorization: Bearer <token>, X-Tenant-Id: <tenantId>

Query (typical): limit, next, status, from, to, sortBy, sortOrder (per OpenAPI).

Response

Get one delivery

Endpoint: GET /hub/v1/webhooks/deliveries/{id}/get (getDeliveryQuery)
Headers: Authorization: Bearer <token>, X-Tenant-Id: <tenantId> (per spec)

Use this to inspect payload metadata, status, and errors for a single delivery attempt.

Retry a failed delivery

Endpoint: POST /hub/v1/webhooks/deliveries/{id}/retry
Headers: Authorization: Bearer <token>, X-Tenant-Id: <tenantId>

Response: 202 Accepted — Hub queues a retry. Combine with the deliveries list to recover from transient 5xx responses on your server.

9. API Reference

Subsections follow the service path prefix on the unified API base URL: /identity/v1, /catalog/v1, /screening/v1, /consult/v1, /clinical/v1, /commerce/v1, /hub/v1.

1. Identity (/identity/v1)

2. Catalog (/catalog/v1)

3. Screening (/screening/v1)

4. Consult (/consult/v1)

5. Clinical (/clinical/v1)

6. Commerce (/commerce/v1)

7. Hub (/hub/v1)

All non-catalog endpoints require **Authorization: Bearer **** and **X-Tenant-Id unless the operation explicitly omits tenant scope (e.g. GET /hub/v1/webhooks/event-types/search per bundled spec).

10. Object reference

Types are grouped by the same service prefixes as §9 API Reference: Shared, Identity (/identity/v1), Catalog (/catalog/v1), Screening (/screening/v1), Consult (/consult/v1), Clinical (/clinical/v1), Commerce (/commerce/v1), Hub (/hub/v1). Shared types are reused across services. For fields omitted below, see CareAtlas-Unified-API-oas3-v0.1.json.

Shared types

Address

Used on commerce OrderImportRequest, practitioner onboard, and (as AddressInfo) on PatientResolveRequest. Patient update uses PatientAddressInfo (same required fields; optional label).

---

Identity (/identity/v1)

MyTenantsResponse

200 from GET /identity/v1/tenants/me.

MyTenantsPartnerAppResponse

MyTenantsPartnerResponse

Nested under MyTenantsPartnerAppResponse.partner.

MyTenantsTenantResponse

Each element of tenants or tenantProviders.

MyTenantsAttributeResponse

Name/value pair used on MyTenantsTenantResponse and MyTenantsPartnerAppResponse.

---

PatientResponse

Returned by patient search, resolve, and get-patient flows. Tenant context is X-Tenant-Id on the request, not a field on this object.

Removed from unified PatientResponse: top-level tenantId and accountId — use account.id instead of accountId.

---

OnboardClinicRequest

Request body for POST /identity/v1/tenants/clinics/onboard:

attributes: name, npi, addressId (UUID), email, phone, description.

---

PractitionerOnboardRequest

Request body for POST /identity/v1/practitioners/onboard (create or find practitioner by NPI):

---

PractitionerResponse

Returned by GET /identity/v1/practitioners/search (each item in data) and in POST .../practitioners/onboard response:

---

TenantResponse

Returned by POST /identity/v1/tenants/clinics/onboard and in clinic search results:

Use with address/attribute data to build ClinicInfo for order import.

---

Catalog (/catalog/v1)

Search and product payloads use GetProductResponse (informally called ProductResponse in this guide). Variants carry productVariantId and uomId for prescriptions and order lines.

GetProductResponse

Returned from GET /catalog/v1/products/search and GET /catalog/v1/products/{id}/find.

ProductVariantInfo

Each variant maps to a prescribe-able SKU and order line.

---

Screening (/screening/v1)

CreateSessionRequest

Body for POST /screening/v1/sessions/create.

CreateSessionResponse

201 response from session create; id is the screening session id for /next, /answer, /submit, etc.

ActiveQuestionnaireResponse

Rows from GET /screening/v1/questionnaires/active (each element describes an available questionnaire).

SessionSubmitRequest

Body for POST /screening/v1/sessions/{id}/submit.

SubmitSessionResponse

200 body after submit; use recommendedProductVariants when your clinical flow suggests variants.

AnswerBundleRequest

Body for POST /screening/v1/sessions/{id}/answer.

---

Consult (/consult/v1)

CreateConsultRequest

Body for POST /consult/v1/consults/create (createConsult).

CreateConsultResponse

200 from create consult; use id as consult id on GET/messages routes.

GetConsultResponse

Returned by GET /consult/v1/consults/{id}/get.

ConsultParticipantDto

Each item in GetConsultResponse.participants (and AddParticipantResponse after POST …/participants/add).

The unified partner API does not expose roleId on this type. Role-based participant management (e.g. admin picklists) uses separate admin CRUD routes under /consult/v1/consults/{id}/participants, not participants/add.

AddParticipantRequest

Body for POST /consult/v1/consults/{id}/participants/add.

The consult’s patientId is assigned on the created row by the API; it is not sent in the request.

AddParticipantResponse

201 from POST /consult/v1/consults/{id}/participants/add.

CloseConsultResponse

200 from POST /consult/v1/consults/{id}/close.

CancelConsultResponse

200 from POST /consult/v1/consults/{id}/cancel.

PostMessageRequest

Body for POST /consult/v1/consults/{id}/messages/post.

UpdateMessageDeliveryRequest

Body for POST /consult/v1/consults/{id}/messages/{messageId}/update-delivery.

Path {messageId} is the consult message id (from ConsultMessageResponse / search messages).

UpdateMessageDeliveryResponse

200 from POST /consult/v1/consults/{id}/messages/{messageId}/update-delivery.

---

Clinical (/clinical/v1)

ValidatePrescriptionResponse

Returned by GET /clinical/v1/prescriptions/{id}/validate.

---

CreatePrescriptionCommandRequest

Request body for POST /clinical/v1/prescriptions/create (OpenAPI: CreatePrescriptionRequest).

---

SubmitPaymentRequest

Body for POST /commerce/v1/payments/submit (submitPayment). Records a payment against an order entity in Commerce.

SubmitPaymentResponse

200 from submit payment — includes id, tenantId, intentId, status, amount, etag, and related fields mirroring the request.

---

MedPrescribedInternal

One element of medsPrescribed in CreatePrescriptionCommandRequest.

---

UpdatePrescriptionCommandRequest

Request body for PATCH /clinical/v1/prescriptions/{id}/update. All fields are optional in the bundled schema.

---

PrescriptionResponse

Relevant fields for building the order:

---

Commerce (/commerce/v1)

ClinicInfo

Required by the API schema for OrderImportRequest.

If your backend accepts orders without clinic, you may still need to send a minimal object; confirm with the API or backend team.

---

CustomerInfo

---

LineInfo

---

OrderImportRequest

Full request body for POST /commerce/v1/orders/import. The API schema marks these as required: externalOrderId, customer, clinic, currencyISO, pricing, lines, promos, totals, shippingAddress, billingAddress, payment, validatedAtUtc, source, notes.

---

OrderResponse

Returned by POST /commerce/v1/orders/import:

---

PaymentInfo

Extended payment payload (as used after Stripe) may include intentId, provider (e.g. "Stripe").

---

SourceInfo

---

TotalsInfo

In this app, totals are often sent as strings (e.g. "0", "12.99") for decimal precision.

---

Hub (/hub/v1)

Webhook subscription and delivery types for §8 Working with Webhooks. Requests use Hub Cognito scopes (api://haas.hub/haas.api.read / …write).

CreateSubscriptionRequest

Body for POST /hub/v1/webhooks/subscriptions/create.

CreateSubscriptionResponse

201 — treat signingSecret as sensitive; persist it to verify signatures on inbound webhooks.

UpdateSubscriptionResponse

200 from PATCH /hub/v1/webhooks/subscriptions/{id}/update — same fields as create response except signingSecret (use rotate-secret to obtain a new secret).

GetDeliveryResponse

Returned by GET /hub/v1/webhooks/deliveries/{id}/get for observability and debugging.

11. Troubleshooting

• 401 Unauthorized – Check Cognito token and scope (api://haas.commerce/haas.api.write for import).
• 403 Forbidden – Verify X-Tenant-Id and that the token is allowed for that tenant.
• 400 Bad Request – Validate OrderImportRequest: required fields (including clinic), address fields (addressLine2 must be present, can be ""), and numeric/string formats for qty, unitPrice, lineTotal, totals.
• Missing accountId – Ensure patient has accountId or resolve it via your identity/profile API before calling order import.
• Patient does not have address – Order import requires full shipping and billing addresses; create or update the patient’s address via Identity APIs first.
• Duplicate orders – Use Idempotency-Key (e.g. prescription id + payment id) on POST /commerce/v1/orders/import when retrying or handling webhooks.

For payload examples and mapping from prescription to order, see Build OrderImportRequest and call Import Order and the sample request there.