{"openapi":"3.1.0","info":{"title":"NezerCare Integration API","version":"1.1.0","summary":"Connect the patient widget and clinical workflows to NezerCare.","description":"NezerCare is the patient-care layer between your healthcare platform and your clinical workflow, whether you run a telehealth service, a clinic or practice, or a platform that serves them.\n\n## Quick start\n\n1. Make sure your organization has signed its BAA (an owner or administrator signs it in the dashboard under Settings → Data and compliance). API keys, webhooks and every patient feature stay off until it's signed.\n2. Create an **API key** in the dashboard under Integrations → API keys.\n3. Send it on every request as `Authorization: Bearer nzh_prod_…` to `https://api.nezercare.com`. The paths in this file (`/v1/...`) are relative to that address, which has no `/api` prefix. To try requests by hand, import this file into Postman (or any OpenAPI client) and set the key there.\n4. Put the widget on your site. Verify your website first (dashboard: Integrations → Patient widget): the snippet appears there once a website is verified, and the widget loads, and patients can sign in, only on a verified website. `http://localhost` doesn't count on the hosted service, so build against an address on your verified domain that you've listed under Edit websites (a subdomain counts), and try the widget in the dashboard's Playground before then. Then sign your patients into the widget with a short-lived identity token: your patient identifier as `sub`, plus `given_name` and `email`. That's how patients get into NezerCare: a patient NezerCare doesn't know yet is added the first time your site signs them in. (If you have your own patient portal and want to use NezerCare through the API instead of the widget, your server identifies the patient with `POST /v1/patients/identify`: see **Patient messaging**.)\n5. Subscribe your endpoint to `clinical_case.opened`. When a case arrives, send a `processed` update, then carry on through the clinical-case API. The `handoff` paths in that event start with `/api/v1/...`: on `https://api.nezercare.com` leave the `/api` off.\n\nKeep API keys on your server. Rotate any credential that has been pasted into chat, logs, source control, or another untrusted location.\n\n## API keys\n\nEach organization has one workspace, and a key reaches only the organization that issued it, at `https://api.nezercare.com`. Every organization's one workspace is production, and new keys begin with `nzh_prod_`. A key made before October 2026 keeps working if it belongs to the workspace the organization kept, whatever its prefix (`nzh_sb_` or `nzh_prod_`). A key that belonged to the copy the organization didn't keep (most often an `nzh_sb_` sandbox key of an organization that went live in production) gets `409` with code `ENVIRONMENT_RETIRED` on every request: create a new key in the workspace. To try requests without reaching real patients, sign yourself (or a colleague) into the widget on your site, so the patient is you.\n\nA key does only what it was made for. When you create it (Integrations, API keys) you choose what it may do, at least one of: `care_handoff` (the clinical-case routes: progress, updates including resolving a case, and provider messages), `conversation_gateway` (the conversation routes: read a conversation's patient-visible messages, send as your system, report delivery), `conversation_internal_notes` (on top of the gateway: read the care team's staff-only internal notes with `includeInternal=true`) and `portal_messaging` (patient messaging, below). A call to a route the key wasn't made for gets `403` with code `INSUFFICIENT_SCOPE`, before anything is read or changed, and a key never gains a scope later: make a new key. Keys made before scopes were enforced have `care_handoff` and `conversation_gateway` and work as they did; they don't have `conversation_internal_notes`.\n\nOnly an owner or administrator can give a key `conversation_internal_notes` or `portal_messaging`. Patient messaging (Patient messaging, below) also needs the owner or administrator to confirm that the clinic's portal meets the safety requirements (it always shows a 911 line, shows emergency notices at once and never hides them, and doesn't answer health questions with its own AI in these conversations). The confirmation is recorded and audited.\n\nReads through the conversation gateway are recorded in the workspace's audit log (the key and the conversation, never the messages).\n\nA key beginning `nzh_test_` is a NezerCare setup test key, given out while NezerCare sets a workspace up and before the clinic is invited. Every request with it sees only NezerCare's made-up test patients (a real patient's or case's ID answers `404`), it works before the BAA is signed, and it can't be rotated. It stops working, with every test patient, when the clinic's invitation is sent.\n\n## Idempotency and ordering\n\nEvery case update, provider message, and conversation message carries a caller-generated UUID. Retry an uncertain request using the **same UUID and identical body**: the original result comes back with `duplicate: true` (status `200` on the clinical-case routes, `201` on a conversation message). Reusing the UUID with different content returns `409`. Case updates must use the consecutive `nextSequence` returned by the progress endpoint. In patient messaging, each message of a conversation has a `sequence` (1, 2, 3 with no gaps): apply messages by `sequence`, not by arrival, and pull with `afterSequence` to fill any gap. The webhooks `conversation.message_created` and `conversation.updated` are delivered at least once, in parallel, with no promised order: deduplicate by `x-nezer-event-id` and by the message ID.\n\n## Errors and limits\n\nErrors are JSON with a `message` (a sentence, or a list of sentences when a request failed validation) and, where one applies, a `code`; the case, conversation and validation errors of the clinical-case and conversation routes are the web framework's standard ones and also carry `error` and `statusCode`. Validation errors return `400` (a field the operation doesn't take is refused, not ignored); a missing key returns `401` with code `MISSING_API_CREDENTIAL`, and an invalid, expired or revoked one `401` with code `INVALID_API_CREDENTIAL`; a key of a retired workspace gets `409` with code `ENVIRONMENT_RETIRED` (don't retry it: use a new key); an organization without a signed BAA gets `403` with code `BAA_REQUIRED` on every call (don't retry it: sign the BAA, then call again); signing a patient into the widget from a page that isn't one of your verified websites gets `403` with code `WEBSITE_NOT_VERIFIED` (no patient is added and the identity token isn't used up: verify the website, then sign in again); tenant-scoped missing resources return `404`; idempotency and ordering conflicts return `409`; a `scheduled` case update without a valid `visitUrl` returns `400` with code `VISIT_URL_REQUIRED`, `VISIT_URL_INVALID` or `VISIT_URL_NOT_ALLOWED`, and an `appointment_cancelled` update with no appointment to cancel `409` with code `NO_APPOINTMENT_TO_CANCEL`. Retry network errors and `5xx` responses with exponential backoff and jitter. Do not automatically retry most `4xx` responses. Opening a patient's widget session (`POST /v1/widget/sessions`), a launch link (`POST /v1/patient-launches/consume`) and the widget's public config are limited per network address (`429` with code `RATE_LIMITED`; a patient limited this way simply tries again in a few minutes). Patient messaging adds its own limits: a patient may send 20 messages a minute, an API key may send 600 requests a minute and 20,000 an hour, counted over every route it can call (patient messaging, the conversation gateway and the care hand-off together), and start 60 new conversations a minute and 1,000 an hour (each `429` with code `RATE_LIMITED` and `Retry-After`, and never for an emergency message; an emergency is answered first with the 911 notice but only so many a key sends an hour are stored, as the message routes explain), and a workspace may add 500 new patients an hour through `identify` (`429` with code `PATIENT_CAP_REACHED`). An API key may also use a number of credits a day (500 unless the workspace chose another); past it, its patients' messages are not refused but go to the care team without an AI reply until midnight UTC. Honor `Retry-After`, and handle a `429` on other routes too, in case more limits come. A key without the `portal_messaging` scope gets `403` with code `INSUFFICIENT_SCOPE` on patient messaging.\n\n## Changes\n\n**1.1.0 (October 2026), a breaking change to case updates.** A `scheduled` update now requires `visitUrl`, the link the patient joins the visit with (`https` only, at most 2000 characters, a real website name, no username or password): without a valid one it is `400` with code `VISIT_URL_REQUIRED`, `VISIT_URL_INVALID` or `VISIT_URL_NOT_ALLOWED`. It used to be accepted without one; send the link on every `scheduled` update, including a move. A retry of an update you sent before the change, unchanged, still answers `200` with `duplicate: true`. New: the `appointment_cancelled` update status (`409 NO_APPOINTMENT_TO_CANCEL` when there is nothing to cancel); the progress endpoint's `scheduledFor` is now the case's appointment (kept after later updates until it is cancelled or the case is resolved) and `hasVisitLink` is added; the patient is emailed reminders a day and an hour before an appointment, and a cancellation notice; and the conversation of Patient messaging carries `appointment` (`scheduledFor`, `visitUrl`).\n\n## Clinical boundary\n\nWebhook delivery confirms transport only. It never means a clinician reviewed the case. NezerCare has no appointment-booking API: if your clinical system schedules care, report it with a `scheduled` case update (with the `visitUrl` the patient joins the visit with) and cancel it with `appointment_cancelled`. Only an explicit resolution closes a case: your `resolved` update, or a team member resolving it in NezerCare.","contact":{"name":"NezerCare integration support"}},"servers":[{"url":"https://api.nezercare.com","description":"NezerCare"}],"security":[{"bearerAuth":[]}],"tags":[{"name":"Workflows","description":"The staff app's endpoints for building, testing and switching on the workflows the agent runs for signed-in patients. They need a Firebase workforce token with `integrations.manage`; changes need MFA, and so does reading a workflow's runs. Environment API keys are not accepted. Test runs call your real connections with a sample patient but never message a patient."},{"name":"Patient searches","description":"The staff app's endpoints for the searches @Nezer runs in your own system to find who a group message in Slack is for. They need a Firebase workforce token with `integrations.manage`; every change and test needs MFA, and reviewing one NezerCare set up also needs `organization.settings.manage`. Environment API keys are not accepted."},{"name":"Patient messaging","description":"Use NezerCare from your own patient portal instead of the widget (headless messaging). Your server identifies a patient it has authenticated, then sends the patient's messages and reads the conversation; NezerCare does the rest exactly as it does for the widget: the emergency check first on every message, health concerns carried through the clinic's approved questions to the patient's review and the care team and never answered by AI, requests for the other teams gathered in a short guided chat, the workflows the clinic built, everyday questions answered from your knowledge with sources, photos and PDFs, and the care team's replies back in the same feed, and by signed webhook (`conversation.message_created`, `conversation.updated`). Whether NezerCare also emails the patient about a reply is the clinic's setting (Integrations, Patient messaging). That email goes to the address you gave `identify`, from NezerCare as \"Your Clinic via NezerCare\", and a workspace may send only so many an hour (30 emails to 20 different addresses on the free trial, 500 to 400 on a paid plan; one past that waits for the hour and is sent). Give NezerCare only addresses your patients gave you. Needs an API key with the `portal_messaging` scope, which an owner or administrator turns on when creating the key after confirming that the portal meets the safety requirements (it always shows a 911 line, shows emergency notices at once and never hides them, and does not answer health questions with its own AI in these conversations). Server to server only: keep the key on your servers. The widget's website verification doesn't apply."},{"name":"Clinical cases","description":"Confirm processing, report clinical progress, send patient-visible messages, and explicitly resolve escalated cases."},{"name":"Conversations","description":"One ordered message thread for a clinical case or work item. Read messages after a sequence number, send a message from your system with a caller-generated `requestId`, and report delivery (`delivered`, `read` or `failed`). A conversation only carries messages: it can't resolve a case or make a care decision. The routes work on a conversation whose ID you already have: this API has no call that lists conversations or finds one, and no webhook announces them. A patient portal doesn't use these routes: it uses Patient messaging, which has its own conversations, runs the emergency check on every message and never returns an internal note."},{"name":"Webhooks","description":"Events NezerCare sends to your endpoints. Add an endpoint in the dashboard under Integrations → Notifications; its signing secret is shown once. An endpoint is a `POST` address of your own: `https` on a public DNS name (not an IP address, `localhost` or a `.local` name), up to 10 for a workspace.\n\nVerify `x-nezer-signature` against the **raw request bytes** before parsing JSON. Compute the lowercase hexadecimal HMAC-SHA256 of `<x-nezer-timestamp>.<raw-body>` (the timestamp is in seconds since the epoch) using the endpoint signing secret and compare it to the value after `v1=` using a constant-time comparison. Reject a timestamp more than five minutes from now, and deduplicate by `x-nezer-event-id`.\n\n**Delivery.** Each request carries `content-type: application/json`, `user-agent: NezerHealth-Webhooks/1.0` and the headers listed on each event. Answer with any `2xx` within 5 seconds, once the event is stored durably: any other status, a redirect (NezerCare doesn't follow redirects), a connection failure or no answer in time fails the attempt. A failed delivery is retried after 2, 4, 8 … seconds, doubling up to about 17 minutes, and stops after 12 attempts (about 51 minutes after the first); a team member can send it again from the dashboard. Every retry reuses the event's `x-nezer-event-id` and is signed afresh, with a new timestamp. An address that gives no answer in time on 10 attempts in a row, over at least 10 minutes, is paused: nothing more is sent to it until someone in the dashboard presses Resume, and what waited is sent then. An endpoint can also be set to send an `Authorization` header (bearer or basic) or a header of your choosing with each request.\n\nWorkflow calls to your own systems (Destinations) are signed too, with your workspace's **widget signing secret**: `x-nezer-signature` is the HMAC-SHA256 of `<x-nezer-timestamp>.<METHOD> <path and query>\\n<raw body>`. `order_lookup.requested` below is the order lookup contract an \"Order status and tracking\" workflow holds your order system to, and `patient_search.requested` is the patients_v1 call @Nezer makes to find who a group message in Slack is for, signed the same way.\n\nThe event catalog is the clinical-case events, the two portal conversation events, `patient.deleted` and two account events, `billing.usage_threshold_reached` and `subscription.updated`, sent to every endpoint subscribed to them. `billing.usage_threshold_reached` is sent once each as use reaches 80%, 95% and 100% of the month's credits, with `unit: \"credits\"`, `threshold`, `creditsUsed`, `monthlyCredits`, `remaining` and `paused` (an older plan with a monthly active-patient limit sends `unit: \"active_patients\"`, `activePatients` and `activePatientLimit` instead). Subscription updates carry `status` (`trialing`, `active`, `past_due`, `grace_period`, `restricted`, `canceled` or `enterprise`), `plan`, `reason`, `recovered` and `invoicePastDue`; grace expiry uses reason `PAYMENT_GRACE_PERIOD_EXPIRED`, and a paid invoice that follows a failed payment carries `recovered: true` (a first or ordinary monthly charge has `false`). An Enterprise subscription invoiced by NezerCare reports `enterprise`, with `invoicePastDue: true` while an invoice is overdue: the plan's own, or the invoice for a credit top-up (an update is sent when a top-up invoice becomes overdue, and when it's paid or voided after that). Clinical event bodies may contain protected health information and must not be written to ordinary logs.\n\nUntil the organization signs its BAA, every event that is about patients (the clinical-case events, the portal conversation events and `patient.deleted`) is held (not dropped, and no attempt is used) and goes out once it's signed. `billing.usage_threshold_reached` and `subscription.updated` are about your account and carry no patient data, so they're never held for the BAA."}],"paths":{"/organizations/{organizationId}/environments/{environmentId}/conversation-workflows":{"get":{"tags":["Workflows"],"summary":"List workflows","description":"Every workflow and its versions, archived ones included (`archivedAt`). `everLive` says whether it has ever been switched on or run, which decides between Delete and Archive.","security":[{"workforceAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"environmentId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Successful read or update."},"201":{"description":"Successful POST operation."},"400":{"description":"Invalid definition, or not ready to switch on."},"401":{"description":"Workforce authentication required."},"403":{"description":"Permission or MFA requirement not met, or (code BAA_REQUIRED) a test run would call a real Destination before the organization has signed its BAA."},"404":{"description":"Not found in the organization's workspace."},"409":{"description":"Stale revision, duplicate key, a version that can no longer change, a workflow that has been live (archive it instead of deleting it), or an archived workflow (restore it before editing or switching it on)."}}},"post":{"tags":["Workflows"],"summary":"Create a workflow","description":"Its first version is a draft.","security":[{"workforceAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"environmentId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["stableKey","name","definition"],"properties":{"stableKey":{"type":"string","pattern":"^[a-z][a-z0-9_]{1,79}$"},"name":{"type":"string","minLength":1,"maxLength":120},"definition":{"$ref":"#/components/schemas/WorkflowDefinition"}}}}}},"responses":{"200":{"description":"Successful read or update."},"201":{"description":"Successful POST operation."},"400":{"description":"Invalid definition, or not ready to switch on."},"401":{"description":"Workforce authentication required."},"403":{"description":"Permission or MFA requirement not met, or (code BAA_REQUIRED) a test run would call a real Destination before the organization has signed its BAA."},"404":{"description":"Not found in the organization's workspace."},"409":{"description":"Stale revision, duplicate key, a version that can no longer change, a workflow that has been live (archive it instead of deleting it), or an archived workflow (restore it before editing or switching it on)."}}}},"/organizations/{organizationId}/environments/{environmentId}/conversation-workflows/connections":{"get":{"tags":["Workflows"],"summary":"List connections a step can call","description":"The connections (Destinations) a Call API step could use, marked when they are your own systems rather than a provider network. Needs no MFA.","security":[{"workforceAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"environmentId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Successful read or update."},"201":{"description":"Successful POST operation."},"400":{"description":"Invalid definition, or not ready to switch on."},"401":{"description":"Workforce authentication required."},"403":{"description":"Permission or MFA requirement not met, or (code BAA_REQUIRED) a test run would call a real Destination before the organization has signed its BAA."},"404":{"description":"Not found in the organization's workspace."},"409":{"description":"Stale revision, duplicate key, a version that can no longer change, a workflow that has been live (archive it instead of deleting it), or an archived workflow (restore it before editing or switching it on)."}}}},"/organizations/{organizationId}/environments/{environmentId}/conversation-workflows/templates":{"get":{"tags":["Workflows"],"summary":"List workflow templates","description":"Ready-made workflows, grouped by the kind of request they handle (orders and shipping, billing and plans, appointments, refills and pharmacy, account), each with the definition it starts from.","security":[{"workforceAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"environmentId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Successful read or update."},"201":{"description":"Successful POST operation."},"400":{"description":"Invalid definition, or not ready to switch on."},"401":{"description":"Workforce authentication required."},"403":{"description":"Permission or MFA requirement not met, or (code BAA_REQUIRED) a test run would call a real Destination before the organization has signed its BAA."},"404":{"description":"Not found in the organization's workspace."},"409":{"description":"Stale revision, duplicate key, a version that can no longer change, a workflow that has been live (archive it instead of deleting it), or an archived workflow (restore it before editing or switching it on)."}}}},"/organizations/{organizationId}/environments/{environmentId}/conversation-workflows/templates/{templateKey}":{"post":{"tags":["Workflows"],"summary":"Add a workflow from a template","description":"Adds the template as a draft workflow (its first version), to adjust and test before it is switched on. If its key or name is already taken, the copy gets a number (`order_status_2`). `404` for a template key that doesn't exist.","security":[{"workforceAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"environmentId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"templateKey","in":"path","required":true,"description":"The template's key, such as `order_status`.","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful read or update."},"201":{"description":"Successful POST operation."},"400":{"description":"Invalid definition, or not ready to switch on."},"401":{"description":"Workforce authentication required."},"403":{"description":"Permission or MFA requirement not met, or (code BAA_REQUIRED) a test run would call a real Destination before the organization has signed its BAA."},"404":{"description":"Not found in the organization's workspace."},"409":{"description":"Stale revision, duplicate key, a version that can no longer change, a workflow that has been live (archive it instead of deleting it), or an archived workflow (restore it before editing or switching it on)."}}}},"/organizations/{organizationId}/environments/{environmentId}/conversation-workflows/{profileId}":{"patch":{"tags":["Workflows"],"summary":"Rename a workflow","description":"Staff see the name; patients don't.","security":[{"workforceAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"environmentId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"profileId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string","minLength":1,"maxLength":120}}}}}},"responses":{"200":{"description":"Successful read or update."},"201":{"description":"Successful POST operation."},"400":{"description":"Invalid definition, or not ready to switch on."},"401":{"description":"Workforce authentication required."},"403":{"description":"Permission or MFA requirement not met, or (code BAA_REQUIRED) a test run would call a real Destination before the organization has signed its BAA."},"404":{"description":"Not found in the organization's workspace."},"409":{"description":"Stale revision, duplicate key, a version that can no longer change, a workflow that has been live (archive it instead of deleting it), or an archived workflow (restore it before editing or switching it on)."}}},"delete":{"tags":["Workflows"],"summary":"Delete a workflow","description":"Only one that has never been live, with its drafts and their test results. Audited. One that has been live is refused with `409`: archive it instead.","security":[{"workforceAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"environmentId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"profileId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Successful read or update."},"201":{"description":"Successful POST operation."},"400":{"description":"Invalid definition, or not ready to switch on."},"401":{"description":"Workforce authentication required."},"403":{"description":"Permission or MFA requirement not met, or (code BAA_REQUIRED) a test run would call a real Destination before the organization has signed its BAA."},"404":{"description":"Not found in the organization's workspace."},"409":{"description":"Stale revision, duplicate key, a version that can no longer change, a workflow that has been live (archive it instead of deleting it), or an archived workflow (restore it before editing or switching it on)."}}}},"/organizations/{organizationId}/environments/{environmentId}/conversation-workflows/{profileId}/archive":{"post":{"tags":["Workflows"],"summary":"Archive a workflow","description":"For one that has been live: it's switched off, out of the list and never matched, with its versions and runs kept. Audited.","security":[{"workforceAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"environmentId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"profileId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Successful read or update."},"201":{"description":"Successful POST operation."},"400":{"description":"Invalid definition, or not ready to switch on."},"401":{"description":"Workforce authentication required."},"403":{"description":"Permission or MFA requirement not met, or (code BAA_REQUIRED) a test run would call a real Destination before the organization has signed its BAA."},"404":{"description":"Not found in the organization's workspace."},"409":{"description":"Stale revision, duplicate key, a version that can no longer change, a workflow that has been live (archive it instead of deleting it), or an archived workflow (restore it before editing or switching it on)."}}}},"/organizations/{organizationId}/environments/{environmentId}/conversation-workflows/{profileId}/restore":{"post":{"tags":["Workflows"],"summary":"Restore a workflow","description":"Brings an archived workflow back, still switched off. Audited.","security":[{"workforceAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"environmentId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"profileId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Successful read or update."},"201":{"description":"Successful POST operation."},"400":{"description":"Invalid definition, or not ready to switch on."},"401":{"description":"Workforce authentication required."},"403":{"description":"Permission or MFA requirement not met, or (code BAA_REQUIRED) a test run would call a real Destination before the organization has signed its BAA."},"404":{"description":"Not found in the organization's workspace."},"409":{"description":"Stale revision, duplicate key, a version that can no longer change, a workflow that has been live (archive it instead of deleting it), or an archived workflow (restore it before editing or switching it on)."}}}},"/organizations/{organizationId}/environments/{environmentId}/conversation-workflows/{profileId}/draft":{"post":{"tags":["Workflows"],"summary":"Create or reuse a draft","description":"Without interrupting the live version.","security":[{"workforceAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"environmentId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"profileId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Successful read or update."},"201":{"description":"Successful POST operation."},"400":{"description":"Invalid definition, or not ready to switch on."},"401":{"description":"Workforce authentication required."},"403":{"description":"Permission or MFA requirement not met, or (code BAA_REQUIRED) a test run would call a real Destination before the organization has signed its BAA."},"404":{"description":"Not found in the organization's workspace."},"409":{"description":"Stale revision, duplicate key, a version that can no longer change, a workflow that has been live (archive it instead of deleting it), or an archived workflow (restore it before editing or switching it on)."}}}},"/organizations/{organizationId}/environments/{environmentId}/conversation-workflows/{profileId}/deactivate":{"post":{"tags":["Workflows"],"summary":"Switch a workflow off","security":[{"workforceAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"environmentId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"profileId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Successful read or update."},"201":{"description":"Successful POST operation."},"400":{"description":"Invalid definition, or not ready to switch on."},"401":{"description":"Workforce authentication required."},"403":{"description":"Permission or MFA requirement not met, or (code BAA_REQUIRED) a test run would call a real Destination before the organization has signed its BAA."},"404":{"description":"Not found in the organization's workspace."},"409":{"description":"Stale revision, duplicate key, a version that can no longer change, a workflow that has been live (archive it instead of deleting it), or an archived workflow (restore it before editing or switching it on)."}}}},"/organizations/{organizationId}/environments/{environmentId}/conversation-workflows/{profileId}/runs":{"get":{"tags":["Workflows"],"summary":"List recent runs","description":"Step by step: outcomes only, never values. Needs a sign-in made with MFA, like a change.","security":[{"workforceAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"environmentId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"profileId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Successful read or update."},"201":{"description":"Successful POST operation."},"400":{"description":"Invalid definition, or not ready to switch on."},"401":{"description":"Workforce authentication required."},"403":{"description":"Permission or MFA requirement not met, or (code BAA_REQUIRED) a test run would call a real Destination before the organization has signed its BAA."},"404":{"description":"Not found in the organization's workspace."},"409":{"description":"Stale revision, duplicate key, a version that can no longer change, a workflow that has been live (archive it instead of deleting it), or an archived workflow (restore it before editing or switching it on)."}}}},"/organizations/{organizationId}/environments/{environmentId}/conversation-workflows/versions/{versionId}":{"put":{"tags":["Workflows"],"summary":"Save a draft","description":"Saves the current draft revision.","security":[{"workforceAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"environmentId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"versionId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["expectedRevision","definition"],"properties":{"expectedRevision":{"type":"integer","minimum":1},"definition":{"$ref":"#/components/schemas/WorkflowDefinition"}}}}}},"responses":{"200":{"description":"Successful read or update."},"201":{"description":"Successful POST operation."},"400":{"description":"Invalid definition, or not ready to switch on."},"401":{"description":"Workforce authentication required."},"403":{"description":"Permission or MFA requirement not met, or (code BAA_REQUIRED) a test run would call a real Destination before the organization has signed its BAA."},"404":{"description":"Not found in the organization's workspace."},"409":{"description":"Stale revision, duplicate key, a version that can no longer change, a workflow that has been live (archive it instead of deleting it), or an archived workflow (restore it before editing or switching it on)."}}},"delete":{"tags":["Workflows"],"summary":"Discard a draft","description":"Discards the draft on top of a live (or last live) version; that version is untouched. Audited. A workflow's only draft is deleted with the workflow instead.","security":[{"workforceAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"environmentId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"versionId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Successful read or update."},"201":{"description":"Successful POST operation."},"400":{"description":"Invalid definition, or not ready to switch on."},"401":{"description":"Workforce authentication required."},"403":{"description":"Permission or MFA requirement not met, or (code BAA_REQUIRED) a test run would call a real Destination before the organization has signed its BAA."},"404":{"description":"Not found in the organization's workspace."},"409":{"description":"Stale revision, duplicate key, a version that can no longer change, a workflow that has been live (archive it instead of deleting it), or an archived workflow (restore it before editing or switching it on)."}}}},"/organizations/{organizationId}/environments/{environmentId}/conversation-workflows/versions/{versionId}/readiness":{"get":{"tags":["Workflows"],"summary":"Check readiness","description":"What still blocks switching this version on.","security":[{"workforceAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"environmentId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"versionId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Successful read or update."},"201":{"description":"Successful POST operation."},"400":{"description":"Invalid definition, or not ready to switch on."},"401":{"description":"Workforce authentication required."},"403":{"description":"Permission or MFA requirement not met, or (code BAA_REQUIRED) a test run would call a real Destination before the organization has signed its BAA."},"404":{"description":"Not found in the organization's workspace."},"409":{"description":"Stale revision, duplicate key, a version that can no longer change, a workflow that has been live (archive it instead of deleting it), or an archived workflow (restore it before editing or switching it on)."}}}},"/organizations/{organizationId}/environments/{environmentId}/conversation-workflows/versions/{versionId}/test":{"post":{"tags":["Workflows"],"summary":"Test a version","description":"Runs a saved version with a sample patient; returns whether it passed, the transcript and each step's request and response. A test that runs to its end uses a workflow run's credits (two), like a live one, and is refused (`423 NEZER_PAUSED`) while the workspace is paused; each person may run 30 tests an hour.","security":[{"workforceAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"environmentId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"versionId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["expectedRevision","opening","replies"],"properties":{"expectedRevision":{"type":"integer","minimum":1},"opening":{"type":"string","minLength":1,"maxLength":2000,"example":"Where is my order?"},"replies":{"type":"array","maxItems":20,"items":{"type":"string","minLength":1,"maxLength":500},"example":["A10001"]},"patientEmail":{"type":"string","maxLength":200,"description":"The sample patient's email, for ownership checks and {{patient.email}}."},"patientId":{"type":"string","maxLength":200,"description":"Or the sample patient's ID in your system; also sent as {{patient.externalId}} (order lookups use it)."}}}}}},"responses":{"200":{"description":"Successful read or update."},"201":{"description":"Successful POST operation."},"400":{"description":"Invalid definition, or not ready to switch on."},"401":{"description":"Workforce authentication required."},"403":{"description":"Permission or MFA requirement not met, or (code BAA_REQUIRED) a test run would call a real Destination before the organization has signed its BAA."},"404":{"description":"Not found in the organization's workspace."},"409":{"description":"Stale revision, duplicate key, a version that can no longer change, a workflow that has been live (archive it instead of deleting it), or an archived workflow (restore it before editing or switching it on)."}}}},"/organizations/{organizationId}/environments/{environmentId}/conversation-workflows/versions/{versionId}/activate":{"post":{"tags":["Workflows"],"summary":"Switch a version on","description":"Only a draft that passed a test within 24 hours.","security":[{"workforceAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"environmentId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"versionId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["expectedRevision"],"properties":{"expectedRevision":{"type":"integer","minimum":1}}}}}},"responses":{"200":{"description":"Successful read or update."},"201":{"description":"Successful POST operation."},"400":{"description":"Invalid definition, or not ready to switch on."},"401":{"description":"Workforce authentication required."},"403":{"description":"Permission or MFA requirement not met, or (code BAA_REQUIRED) a test run would call a real Destination before the organization has signed its BAA."},"404":{"description":"Not found in the organization's workspace."},"409":{"description":"Stale revision, duplicate key, a version that can no longer change, a workflow that has been live (archive it instead of deleting it), or an archived workflow (restore it before editing or switching it on)."}}}},"/organizations/{organizationId}/environments/{environmentId}/patient-searches":{"get":{"tags":["Patient searches"],"summary":"List patient searches","description":"Every search, with its connection, filters, last test (counts only), what blocks turning it on, and any NezerCare setup hold; and the connections a search may call (your own systems).","security":[{"workforceAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"environmentId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Successful read, update or test."},"201":{"description":"Created."},"400":{"description":"Invalid search, or (code PATIENT_SEARCH_HEALTH_TERMS) one that sounds like it's about patients' health."},"401":{"description":"Workforce authentication required."},"403":{"description":"Permission or MFA requirement not met, NezerCare setup turning a search on or reviewing it (SETUP_REVIEW_REQUIRED), or (code BAA_REQUIRED) a test before the organization has signed its BAA, NezerCare setup's included."},"404":{"description":"Not found in the organization's workspace."},"409":{"description":"Stale revision, a key already used, at most 10 searches, a test before the workspace has a widget signing secret (PATIENT_SEARCH_SIGNING_SECRET_REQUIRED: every call is signed with it), not ready to turn on (PATIENT_SEARCH_NOT_READY: a passing test of the saved version within 24 hours, its connection on and the widget signing secret), held for the clinic's review (SETUP_REVIEW_REQUIRED), or not held (NOT_HELD_FOR_REVIEW)."}}},"post":{"tags":["Patient searches"],"summary":"Add a patient search","description":"Saved off. Audited as patient_search.created.","security":[{"workforceAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"environmentId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatientSearchDefinition"}}}},"responses":{"200":{"description":"Successful read, update or test."},"201":{"description":"Created."},"400":{"description":"Invalid search, or (code PATIENT_SEARCH_HEALTH_TERMS) one that sounds like it's about patients' health."},"401":{"description":"Workforce authentication required."},"403":{"description":"Permission or MFA requirement not met, NezerCare setup turning a search on or reviewing it (SETUP_REVIEW_REQUIRED), or (code BAA_REQUIRED) a test before the organization has signed its BAA, NezerCare setup's included."},"404":{"description":"Not found in the organization's workspace."},"409":{"description":"Stale revision, a key already used, at most 10 searches, a test before the workspace has a widget signing secret (PATIENT_SEARCH_SIGNING_SECRET_REQUIRED: every call is signed with it), not ready to turn on (PATIENT_SEARCH_NOT_READY: a passing test of the saved version within 24 hours, its connection on and the widget signing secret), held for the clinic's review (SETUP_REVIEW_REQUIRED), or not held (NOT_HELD_FOR_REVIEW)."}}}},"/organizations/{organizationId}/environments/{environmentId}/patient-searches/{searchId}":{"put":{"tags":["Patient searches"],"summary":"Change a patient search","description":"Any change turns it off and needs a new test. Audited.","security":[{"workforceAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"environmentId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"searchId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PatientSearchDefinition"},{"type":"object","required":["expectedRevision"],"properties":{"expectedRevision":{"type":"integer","minimum":1}}}]}}}},"responses":{"200":{"description":"Successful read, update or test."},"201":{"description":"Created."},"400":{"description":"Invalid search, or (code PATIENT_SEARCH_HEALTH_TERMS) one that sounds like it's about patients' health."},"401":{"description":"Workforce authentication required."},"403":{"description":"Permission or MFA requirement not met, NezerCare setup turning a search on or reviewing it (SETUP_REVIEW_REQUIRED), or (code BAA_REQUIRED) a test before the organization has signed its BAA, NezerCare setup's included."},"404":{"description":"Not found in the organization's workspace."},"409":{"description":"Stale revision, a key already used, at most 10 searches, a test before the workspace has a widget signing secret (PATIENT_SEARCH_SIGNING_SECRET_REQUIRED: every call is signed with it), not ready to turn on (PATIENT_SEARCH_NOT_READY: a passing test of the saved version within 24 hours, its connection on and the widget signing secret), held for the clinic's review (SETUP_REVIEW_REQUIRED), or not held (NOT_HELD_FOR_REVIEW)."}}},"delete":{"tags":["Patient searches"],"summary":"Remove a patient search","description":"Audited as patient_search.removed.","security":[{"workforceAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"environmentId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"searchId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Successful read, update or test."},"201":{"description":"Created."},"400":{"description":"Invalid search, or (code PATIENT_SEARCH_HEALTH_TERMS) one that sounds like it's about patients' health."},"401":{"description":"Workforce authentication required."},"403":{"description":"Permission or MFA requirement not met, NezerCare setup turning a search on or reviewing it (SETUP_REVIEW_REQUIRED), or (code BAA_REQUIRED) a test before the organization has signed its BAA, NezerCare setup's included."},"404":{"description":"Not found in the organization's workspace."},"409":{"description":"Stale revision, a key already used, at most 10 searches, a test before the workspace has a widget signing secret (PATIENT_SEARCH_SIGNING_SECRET_REQUIRED: every call is signed with it), not ready to turn on (PATIENT_SEARCH_NOT_READY: a passing test of the saved version within 24 hours, its connection on and the widget signing secret), held for the clinic's review (SETUP_REVIEW_REQUIRED), or not held (NOT_HELD_FOR_REVIEW)."}}}},"/organizations/{organizationId}/environments/{environmentId}/patient-searches/{searchId}/test":{"post":{"tags":["Patient searches"],"summary":"Test a patient search","description":"Calls your system with these values and `x-nezer-test: true`, signed with the widget signing secret, and returns whether it passed, the total found, how many IDs were read and how many are patients in Nezer. Never the IDs. When it didn't pass, `reason` says why: `not_ready` (Nezer couldn't call your system: its connection is off or isn't one of your own systems), `failed` (another status, or no answer in time; `httpStatus`) or `invalid` (the answer broke patients_v1, a 200 that isn't JSON included; `problem` names the field). It passes only when @Nezer could use the same answer: every page read within 4, or more than 50 found (then @Nezer asks the team to narrow it). A passing test counts for 24 hours. Needs a signed BAA, even for NezerCare setup, since the answer holds your real patients' IDs, and the widget signing secret.","security":[{"workforceAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"environmentId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"searchId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["expectedRevision"],"properties":{"expectedRevision":{"type":"integer","minimum":1},"values":{"type":"object","additionalProperties":{"type":"object","properties":{"value":{"type":"string"},"from":{"type":"string","format":"date"},"to":{"type":"string","format":"date"}}},"example":{"carrier":{"value":"ups"},"shippedOn":{"from":"2026-09-28","to":"2026-10-04"}}}}}}}},"responses":{"200":{"description":"Successful read, update or test."},"201":{"description":"Created."},"400":{"description":"Invalid search, or (code PATIENT_SEARCH_HEALTH_TERMS) one that sounds like it's about patients' health."},"401":{"description":"Workforce authentication required."},"403":{"description":"Permission or MFA requirement not met, NezerCare setup turning a search on or reviewing it (SETUP_REVIEW_REQUIRED), or (code BAA_REQUIRED) a test before the organization has signed its BAA, NezerCare setup's included."},"404":{"description":"Not found in the organization's workspace."},"409":{"description":"Stale revision, a key already used, at most 10 searches, a test before the workspace has a widget signing secret (PATIENT_SEARCH_SIGNING_SECRET_REQUIRED: every call is signed with it), not ready to turn on (PATIENT_SEARCH_NOT_READY: a passing test of the saved version within 24 hours, its connection on and the widget signing secret), held for the clinic's review (SETUP_REVIEW_REQUIRED), or not held (NOT_HELD_FOR_REVIEW)."}}}},"/organizations/{organizationId}/environments/{environmentId}/patient-searches/{searchId}/enabled":{"put":{"tags":["Patient searches"],"summary":"Turn a patient search on or off","description":"On needs a passing test of the saved version within 24 hours, its connection on and the widget signing secret. Audited.","security":[{"workforceAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"environmentId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"searchId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["enabled"],"properties":{"enabled":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Successful read, update or test."},"201":{"description":"Created."},"400":{"description":"Invalid search, or (code PATIENT_SEARCH_HEALTH_TERMS) one that sounds like it's about patients' health."},"401":{"description":"Workforce authentication required."},"403":{"description":"Permission or MFA requirement not met, NezerCare setup turning a search on or reviewing it (SETUP_REVIEW_REQUIRED), or (code BAA_REQUIRED) a test before the organization has signed its BAA, NezerCare setup's included."},"404":{"description":"Not found in the organization's workspace."},"409":{"description":"Stale revision, a key already used, at most 10 searches, a test before the workspace has a widget signing secret (PATIENT_SEARCH_SIGNING_SECRET_REQUIRED: every call is signed with it), not ready to turn on (PATIENT_SEARCH_NOT_READY: a passing test of the saved version within 24 hours, its connection on and the widget signing secret), held for the clinic's review (SETUP_REVIEW_REQUIRED), or not held (NOT_HELD_FOR_REVIEW)."}}}},"/organizations/{organizationId}/environments/{environmentId}/patient-searches/{searchId}/review":{"post":{"tags":["Patient searches"],"summary":"Review and turn on a search NezerCare set up","description":"Owners and administrators only, never NezerCare setup. Audited as patient_search.setup_reviewed.","security":[{"workforceAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"environmentId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"searchId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Successful read, update or test."},"201":{"description":"Created."},"400":{"description":"Invalid search, or (code PATIENT_SEARCH_HEALTH_TERMS) one that sounds like it's about patients' health."},"401":{"description":"Workforce authentication required."},"403":{"description":"Permission or MFA requirement not met, NezerCare setup turning a search on or reviewing it (SETUP_REVIEW_REQUIRED), or (code BAA_REQUIRED) a test before the organization has signed its BAA, NezerCare setup's included."},"404":{"description":"Not found in the organization's workspace."},"409":{"description":"Stale revision, a key already used, at most 10 searches, a test before the workspace has a widget signing secret (PATIENT_SEARCH_SIGNING_SECRET_REQUIRED: every call is signed with it), not ready to turn on (PATIENT_SEARCH_NOT_READY: a passing test of the saved version within 24 hours, its connection on and the widget signing secret), held for the clinic's review (SETUP_REVIEW_REQUIRED), or not held (NOT_HELD_FOR_REVIEW)."}}}},"/v1/patients/{patientId}/conversations/{conversationId}/attachments":{"post":{"tags":["Patient messaging"],"operationId":"addPatientAttachment","summary":"Add a photo or PDF","description":"A photo or PDF from the patient, with the widget's own limits and checks: up to 10 MB, a JPEG, PNG, WebP, HEIC or PDF (decided by the file's first bytes, never its name or the type you claim), and at most 10 files for a conversation or a workflow run. The file is checked and cleaned before it is stored: a JPEG, PNG or WebP is decoded and saved again (same format, at most 4096 pixels on the long side), so its location, camera details, comments and anything after the image are gone and its orientation is applied; a HEIC has its Exif, XMP and other metadata items erased in place; a PDF is kept exactly as sent unless it holds JavaScript, a launch action, an embedded file, rich media, an XFA form or encryption. A file that can't be accepted for what is in it (it does not decode, has more pixels than its kind can be decoded in — 52 megapixels for a JPEG or PNG, fewer for a progressive JPEG, an interlaced PNG or a WebP — or is such a PDF) is `422 ATTACHMENT_REJECTED`, with one message whatever the reason: tell the patient and let them choose another file; do not retry the same one. Send it as `multipart/form-data` in the field `file`, and send nothing else in the request: one file, and no other form fields (a request with another file, another field or an odd field name is `400 INVALID_REQUEST`, before anything is stored). The care team sees it exactly as a widget upload. It goes to the workflow run that is asking for photos, or to the conversation the care team has with the patient; anywhere else there is nowhere to attach it (`409 ATTACHMENT_NOT_EXPECTED`). Photos for a workflow run are refused while the workspace is paused (the run can't go on); photos for the care team's conversation are taken. Sending the same file again returns the same file (`200`). The `sizeBytes` and `sha256` in the answer are the stored file's, after cleaning, so they can differ from the file you sent. Then list the file in the patient's next message (`attachments`) so the feed shows it, or press `done` under a request for photos. The feed shows a file's name, type and size, never its contents.","security":[{"bearerAuth":[]}],"parameters":[{"name":"patientId","in":"path","required":true,"description":"The patient's NezerCare ID, from `POST /v1/patients/identify`. Another workspace's patient, or one that isn't this conversation's, is `404`.","schema":{"type":"string","format":"uuid"}},{"name":"conversationId","in":"path","required":true,"description":"The conversation's ID, from the response that started it.","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["file"],"properties":{"file":{"type":"string","format":"binary","description":"The photo or PDF."}}}}}},"responses":{"200":{"description":"A file with these bytes was already added: this is it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PortalAttachment"},"example":{"id":"a0b1c2d3-e4f5-4a6b-8c7d-9e0f1a2b3c4d","fileName":"spot.jpg","contentType":"image/jpeg","sizeBytes":482113,"sha256":"3c9a1f5b7d2e4a6c8b0d1e3f5a7c9b2d4e6f8a0b1c3d5e7f9a1b3c5d7e9f0a2b"}}}},"201":{"description":"The file was added.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PortalAttachment"},"example":{"id":"a0b1c2d3-e4f5-4a6b-8c7d-9e0f1a2b3c4d","fileName":"spot.jpg","contentType":"image/jpeg","sizeBytes":482113,"sha256":"3c9a1f5b7d2e4a6c8b0d1e3f5a7c9b2d4e6f8a0b1c3d5e7f9a1b3c5d7e9f0a2b"}}}},"400":{"description":"`INVALID_REQUEST`: no file in the field `file`, a file in another field, more than one file, or any other form field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PortalError"},"example":{"code":"INVALID_REQUEST","message":"Send only the file, in the form field \"file\", with no other form fields."}}}},"401":{"description":"The API key is missing, invalid, expired or turned off.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PortalError"},"example":{"code":"INVALID_API_CREDENTIAL","message":"API credential is invalid."}}}},"403":{"description":"`BAA_REQUIRED` until the organization has signed its BAA (a NezerCare setup test key works before it), or `INSUFFICIENT_SCOPE` when the key doesn't have the `portal_messaging` scope. Don't retry either; tell the patient the message was not sent and keep the 911 line in view.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PortalError"},"example":{"code":"INSUFFICIENT_SCOPE","message":"This API key doesn't have the portal_messaging scope. Create a key with it in Integrations, API keys."}}}},"404":{"description":"`PATIENT_NOT_FOUND` or `CONVERSATION_NOT_FOUND`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PortalError"},"example":{"code":"CONVERSATION_NOT_FOUND","message":"No conversation with this ID for this patient."}}}},"409":{"description":"`ATTACHMENT_NOT_EXPECTED` (nowhere to attach a file right now), `ATTACHMENT_LIMIT_REACHED` (10 files already), `CONVERSATION_CLOSED` or `PATIENT_INACTIVE`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PortalError"},"example":{"code":"ATTACHMENT_NOT_EXPECTED","message":"There is nowhere to attach a file in this conversation right now: files go to a workflow run that asks for photos or to the conversation the care team has with the patient."}}}},"413":{"description":"`ATTACHMENT_TOO_LARGE`: over 10 MB.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PortalError"},"example":{"code":"ATTACHMENT_TOO_LARGE","message":"Files can be up to 10 MB."}}}},"415":{"description":"`ATTACHMENT_TYPE_NOT_ALLOWED`: not a JPEG, PNG, WebP, HEIC or PDF.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PortalError"},"example":{"code":"ATTACHMENT_TYPE_NOT_ALLOWED","message":"A file must be a JPEG, PNG, WebP or HEIC photo, or a PDF (its first bytes decide, not its name)."}}}},"422":{"description":"`ATTACHMENT_REJECTED`: the file can't be accepted for what is in it (a photo that does not decode or is too large to decode, a HEIC that can't be read safely, or a PDF with JavaScript, a launch action, an embedded file, rich media, an XFA form or encryption). One message for every reason.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PortalError"},"example":{"code":"ATTACHMENT_REJECTED","message":"We couldn't accept this file. Please try a different photo or PDF."}}}},"429":{"description":"`RATE_LIMITED`: this API key has sent more requests than it may (an API key may send 600 requests a minute and 20,000 an hour, on any route it can call (this API, the conversation gateway and the care hand-off), and start 60 new conversations a minute and 1,000 an hour). Honor `Retry-After`, then retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PortalError"},"example":{"code":"RATE_LIMITED","message":"This API key is sending requests faster than allowed (600 a minute). Wait for Retry-After, then retry with the same requestId."}}}},"503":{"description":"`PATIENT_FILES_UNAVAILABLE`: storage is temporarily unavailable. No attachment was stored; wait for Retry-After and retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PortalError"},"example":{"code":"PATIENT_FILES_UNAVAILABLE","message":"File storage is temporarily unavailable. Retry the upload."}}}}}}},"/v1/patients/identify":{"post":{"tags":["Patient messaging"],"operationId":"identifyPatient","summary":"Identify a patient","description":"Tells NezerCare who the patient is, adding them the first time. `externalPatientId` is your permanent ID for the patient (1 to 200 characters); the same ID reaches the same patient from the widget. A patient NezerCare doesn't know yet needs a valid `givenName` (1 to 80 characters) and `email`; a known patient is found and their name, email and phone are updated from what you send when they differ. A field left out, or sent invalid, never clears or changes anything. A change to a known patient's name, email or phone is recorded in the workspace's audit log with your key and which fields changed, never the values. No session is opened and no profile is returned: keep `patientId` and name it in every other call. Call it for patients you have authenticated, when they first use messaging. At most 500 new patients per workspace per rolling hour (`429 PATIENT_CAP_REACHED` past it; known patients keep working). A `nzh_test_` key creates test patients only.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatientIdentifyRequest"},"example":{"externalPatientId":"pt_48213","givenName":"Maria","familyName":"Lopez","email":"maria@example.com","phone":"+15555550100"}}}},"responses":{"200":{"description":"A patient NezerCare already knew.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatientIdentifyResponse"},"example":{"patientId":"2c3d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f","externalPatientId":"pt_48213","created":false,"status":"active"}}}},"201":{"description":"A patient added.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatientIdentifyResponse"},"example":{"patientId":"2c3d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f","externalPatientId":"pt_48213","created":true,"status":"active"}}}},"400":{"description":"`PATIENT_PROFILE_REQUIRED`: NezerCare doesn't know this patient yet and no valid `givenName` and `email` were sent. Or `INVALID_REQUEST`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PortalError"},"example":{"code":"PATIENT_PROFILE_REQUIRED","message":"NezerCare doesn't know this patient yet. Send their givenName and email to add them."}}}},"401":{"description":"The API key is missing, invalid, expired or turned off.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PortalError"},"example":{"code":"INVALID_API_CREDENTIAL","message":"API credential is invalid."}}}},"403":{"description":"`BAA_REQUIRED` until the organization has signed its BAA (a NezerCare setup test key works before it), or `INSUFFICIENT_SCOPE` when the key doesn't have the `portal_messaging` scope. Don't retry either; tell the patient the message was not sent and keep the 911 line in view.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PortalError"},"example":{"code":"INSUFFICIENT_SCOPE","message":"This API key doesn't have the portal_messaging scope. Create a key with it in Integrations, API keys."}}}},"404":{"description":"`PATIENT_NOT_FOUND`, only for a `nzh_test_` key: the ID belongs to a real patient, who a test key can't see or reach. It is answered like any patient a test key can't see, never as an ID that is taken. Use a made-up ID.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PortalError"},"example":{"code":"PATIENT_NOT_FOUND","message":"No patient with this ID in this workspace."}}}},"409":{"description":"`PATIENT_INACTIVE`: this patient's care has been cancelled. Or `PATIENT_ID_UNAVAILABLE` (the ID can't be used here) or `ENVIRONMENT_RETIRED`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PortalError"},"example":{"code":"PATIENT_INACTIVE","message":"This patient's care has been cancelled."}}}},"429":{"description":"`PATIENT_CAP_REACHED` (with `Retry-After: 600`): this workspace has added as many patients through the API as it may in an hour. Retry later for a new patient. Or `RATE_LIMITED`: this API key has sent more requests than it may (an API key may send 600 requests a minute and 20,000 an hour, on any route it can call (this API, the conversation gateway and the care hand-off), and start 60 new conversations a minute and 1,000 an hour); honor `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PortalError"},"example":{"code":"PATIENT_CAP_REACHED","message":"This workspace has added as many patients through the API as it may in an hour. Patients NezerCare already knows still work; retry later for a new one."}}}}}}},"/v1/patients/{patientId}/conversations":{"get":{"tags":["Patient messaging"],"operationId":"listPatientConversations","summary":"List the patient's conversations","description":"The patient's conversations, newest activity first, a page at a time: what an inbox screen draws. Each is the same conversation object a turn returns (status, `careStatus`, `appointment`, `showCall911`, what is `awaiting`, `lastSequence`, `version`, and the `safety` words to print). It holds no message text: read a conversation's messages for those. Only this patient's conversations in your workspace are ever listed; another patient's or workspace's ID in the path is `404`.\n\nA list is as the care team's replies last reached it, a second or two behind a reply written just now; reading one conversation, or its messages, is always up to date. Pass the `nextCursor` of a page as `after` for the next one; a cursor is opaque, and one this API didn't return is `400`.","security":[{"bearerAuth":[]}],"parameters":[{"name":"patientId","in":"path","required":true,"description":"The patient's NezerCare ID, from `POST /v1/patients/identify`. Another workspace's patient, or one that isn't this conversation's, is `404`.","schema":{"type":"string","format":"uuid"}},{"name":"status","in":"query","required":false,"description":"Only open, or only closed, conversations.","schema":{"type":"string","enum":["open","closed"]}},{"name":"limit","in":"query","required":false,"description":"At most this many conversations (up to 50).","schema":{"type":"integer","minimum":1,"maximum":50,"default":20}},{"name":"after","in":"query","required":false,"description":"The `nextCursor` of the previous page.","schema":{"type":"string","maxLength":400}}],"responses":{"200":{"description":"A page of the patient's conversations.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PortalConversationList"},"example":{"conversations":[{"id":"4a1c8e90-2b7d-4f36-9c05-7d3e1a6b8f12","patientId":"2c3d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f","externalConversationId":"portal-thread-991","channel":"portal_api","status":"open","careStatus":{"code":"replied","label":"New reply from your care team"},"appointment":null,"showCall911":false,"awaiting":{"type":"none"},"lastSequence":3,"version":4,"language":"en","safety":{"language":"en","emergencyLine":"If this is a medical emergency, call 911.","lines":[{"label":"Call 911","tel":"tel:911"}]},"createdAt":"2026-10-18T15:02:11.000Z","updatedAt":"2026-10-18T15:02:13.000Z"}],"hasMore":false,"nextCursor":null}}}},"400":{"description":"`INVALID_REQUEST`: a `limit` out of range, an unknown `status`, or an `after` that isn't a cursor this API returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PortalError"},"example":{"code":"INVALID_REQUEST","message":"after isn't a cursor this API returned. Use the nextCursor of the previous page."}}}},"401":{"description":"The API key is missing, invalid, expired or turned off.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PortalError"},"example":{"code":"INVALID_API_CREDENTIAL","message":"API credential is invalid."}}}},"403":{"description":"`BAA_REQUIRED` until the organization has signed its BAA (a NezerCare setup test key works before it), or `INSUFFICIENT_SCOPE` when the key doesn't have the `portal_messaging` scope. Don't retry either; tell the patient the message was not sent and keep the 911 line in view.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PortalError"},"example":{"code":"INSUFFICIENT_SCOPE","message":"This API key doesn't have the portal_messaging scope. Create a key with it in Integrations, API keys."}}}},"404":{"description":"`PATIENT_NOT_FOUND`: no such patient in this workspace (another workspace's patient, or a real patient to a `nzh_test_` key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PortalError"},"example":{"code":"PATIENT_NOT_FOUND","message":"No patient with this ID in this workspace."}}}},"429":{"description":"`RATE_LIMITED`: this API key has sent more requests than it may (an API key may send 600 requests a minute and 20,000 an hour, on any route it can call (this API, the conversation gateway and the care hand-off), and start 60 new conversations a minute and 1,000 an hour). Honor `Retry-After`, then retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PortalError"},"example":{"code":"RATE_LIMITED","message":"This API key is sending requests faster than allowed (600 a minute). Wait for Retry-After, then retry with the same requestId."}}}}}},"post":{"tags":["Patient messaging"],"operationId":"startPatientConversation","summary":"Start a conversation","description":"The patient's first message of a new topic. A new unrelated topic is a new conversation, like starting a new chat from the widget's Home.\n\nReturns when NezerCare's replies to this message are ready, in the response: allow up to 60 seconds. The patient's `message` is first, then `replies` (NezerCare's messages, in sequence order).\n\n**The emergency check runs first on every message**, by the same fixed rule the widget uses and the clinic's own extra emergency phrases. No AI, no credits, no limit, and it works while the workspace is paused. A match is filed with the care team as an emergency case, and the response carries `showCall911: true` and `emergency` at the top, with the emergency notice as `replies[0]` (`kind: \"emergency\"`, `priority: \"emergency\"`, the lowest sequence of the turn). **Show it at once, in full, and never hide, delay or rewrite it.** An error response to a message that was an emergency carries the same two fields.\n\nIf an emergency can't be filed with the care team on the first try, the notice is shown all the same (`emergency.sentToCareTeam: false`, the same words) and NezerCare keeps trying until it is filed.\n\nOtherwise the message is handled like the widget handles it:\n\n- A **health concern** starts the Health concerns questions: the safety checks as written and the clinic's approved questions (`kind: \"question\"`, answered by a button or in words), then \"Does this look right?\" (`kind: \"review\"`) with a summary of the patient's own words. Pressing `send` puts it with the care team (`kind: \"handoff\"`); typing instead is a correction. A health question is **never** answered by AI. An urgent concern lets the patient send at once (`send_now`), and one the patient walks away from is filed for them after ten minutes: the next read of the conversation carries the `handoff`.\n- A **billing, scheduling, fulfillment or support request** starts a short guided chat the same way (`question`, `review`, `handoff`).\n- A request the clinic built a **workflow** for runs it: its replies as `text`, an order lookup's orders as `orders`, and what it needs next as a `question` (words, a yes or no, or photos). A run that ends offers the care team (`talk_to_team`).\n- An **everyday business question** is answered from the clinic's own knowledge with its sources (`kind: \"answer\"`, one credit).\n- A message in a conversation the team already has goes into that thread, with no reply from NezerCare.\n\nIf a guided leg can't run (the clinic's intake is switched off), the message goes straight to the right team (`kind: \"handoff\"`). While the workspace is paused (trial ended, or out of credits) the Health concerns questions run with no AI, and anything else goes to the team with a `notice` that replies may be delayed; nothing is charged.\n\nEach model turn of the Health concerns questions or the guided chat is one credit; a workflow run that finishes is two; and a request that reaches the billing, scheduling, fulfillment or support team is opened as a case in Operations, which is two. The patient's message, the emergency notice and sending a health concern to the care team are free, and while the workspace is paused nothing is charged.\n\n**Limits on your API key.** Past a limit on requests or on new conversations (`429 RATE_LIMITED`, see below), a message is refused and the patient should be told it was not sent, but an emergency is never refused. Each API key also has a number of credits it may use a day (500 unless the workspace chose another number, in Integrations, Patient messaging). Past that, the key's messages are **not** refused: they run as a paused workspace's do (no AI reply, nothing charged, every message goes to the care team with a `notice` that replies may be delayed) until the day starts again at midnight UTC.\n\n**Emergencies and what they store.** An emergency is always answered first with the notice, and never refused. But a key that sends hundreds of emergency messages an hour is not a patient in trouble, so NezerCare stores up to 300 emergency messages an hour for a key in full. Past that, a patient whose emergency the care team already has (an unresolved emergency case of theirs from the last 15 minutes) is still answered at once with the 911 notice (`showCall911: true`, `emergency.sentToCareTeam: true`, `duplicate: true`), but **that repeat is not stored**: it is not in the conversation's feed, and the response's `message` and notice are not kept. A different patient, or the same one after the 15 minutes, is filed and stored as always. Always show the notice from the response; do not wait for it to appear in the feed.\n\nSend the same `requestId` to retry: the stored turn comes back (`duplicate: true`), nothing is charged or sent twice, and the same ID with different words is `409 REQUEST_ID_REUSED`. A turn that stopped part way is finished by the retry: the questions are not answered twice and the team is not sent the message twice.","security":[{"bearerAuth":[]}],"parameters":[{"name":"patientId","in":"path","required":true,"description":"The patient's NezerCare ID, from `POST /v1/patients/identify`. Another workspace's patient, or one that isn't this conversation's, is `404`.","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StartConversationRequest"},"example":{"requestId":"9d1f7a52-3c6e-4b85-8f0a-5b2c1d7e9a30","externalConversationId":"portal-thread-991","language":"en","text":"Do you ship to Texas?"}}}},"responses":{"201":{"description":"The conversation, the patient's message and NezerCare's replies.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatientTurnResponse"},"examples":{"answer":{"summary":"An everyday question, answered with its sources","value":{"conversation":{"id":"4a1c8e90-2b7d-4f36-9c05-7d3e1a6b8f12","patientId":"2c3d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f","externalConversationId":"portal-thread-991","channel":"portal_api","status":"open","careStatus":{"code":"received","label":"Received"},"appointment":null,"showCall911":false,"awaiting":{"type":"choice","messageId":"e6f4b7c2-91a0-4d38-8b5e-3c7a2d9f1e04","choices":["helpful","talk_to_team"]},"lastSequence":2,"version":3,"language":"en","safety":{"language":"en","emergencyLine":"If this is a medical emergency, call 911.","lines":[{"label":"Call 911","tel":"tel:911"}]},"createdAt":"2026-10-18T15:02:11.000Z","updatedAt":"2026-10-18T15:02:13.000Z"},"message":{"id":"9d1f7a52-3c6e-4b85-8f0a-5b2c1d7e9a30","sequence":1,"kind":"text","from":{"kind":"patient","label":"You"},"priority":"normal","language":"en","text":"Do you ship to Texas?","createdAt":"2026-10-18T15:02:11.000Z"},"replies":[{"id":"e6f4b7c2-91a0-4d38-8b5e-3c7a2d9f1e04","sequence":2,"kind":"answer","from":{"kind":"nezer","label":"NezerCare"},"priority":"normal","language":"en","text":"Yes, we ship to every US state, including Texas.","answerId":"0b9a3c1e-5d7f-4a28-8e46-2f1b9c0d7a35","sources":[{"title":"Shipping and delivery","url":"https://clinic.example.com/shipping"}],"actions":[],"choices":[{"id":"helpful","label":"Yes, thanks"},{"id":"talk_to_team","label":"Talk to the team"}],"causedByRequestId":"9d1f7a52-3c6e-4b85-8f0a-5b2c1d7e9a30","createdAt":"2026-10-18T15:02:13.000Z"}],"showCall911":false,"emergency":null,"duplicate":false}},"healthConcern":{"summary":"A health concern: the intake asks its safety checks (never an AI answer)","value":{"conversation":{"id":"4a1c8e90-2b7d-4f36-9c05-7d3e1a6b8f12","patientId":"2c3d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f","externalConversationId":"portal-thread-991","channel":"portal_api","status":"open","careStatus":{"code":"received","label":"Received"},"appointment":null,"showCall911":false,"awaiting":{"type":"choice","messageId":"b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e","choices":["yes","no","unsure"]},"lastSequence":5,"version":3,"language":"en","safety":{"language":"en","emergencyLine":"If this is a medical emergency, call 911.","lines":[{"label":"Call 911","tel":"tel:911"}]},"createdAt":"2026-10-18T15:02:11.000Z","updatedAt":"2026-10-18T15:02:13.000Z"},"message":{"id":"9d1f7a52-3c6e-4b85-8f0a-5b2c1d7e9a30","sequence":1,"kind":"text","from":{"kind":"patient","label":"You"},"priority":"normal","language":"en","text":"I have a new rash on my arm","createdAt":"2026-10-18T15:02:11.000Z"},"replies":[{"id":"0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c02","sequence":2,"kind":"text","from":{"kind":"nezer","label":"NezerCare"},"priority":"normal","language":"en","text":"I'm sorry you're dealing with this. I'll ask a few quick questions so your care team has what they need.","causedByRequestId":"9d1f7a52-3c6e-4b85-8f0a-5b2c1d7e9a30","createdAt":"2026-10-18T15:04:40.000Z"},{"id":"0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c03","sequence":3,"kind":"text","from":{"kind":"nezer","label":"NezerCare"},"priority":"normal","language":"en","text":"I want to make sure you're safe, so I have a few quick safety questions.","causedByRequestId":"9d1f7a52-3c6e-4b85-8f0a-5b2c1d7e9a30","createdAt":"2026-10-18T15:04:40.000Z"},{"id":"b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e","sequence":4,"kind":"question","from":{"kind":"nezer","label":"NezerCare"},"priority":"normal","language":"en","text":"Is the redness spreading, or are there red streaks from the spot?","purpose":"safety_check","input":{"type":"choice","choices":[{"id":"yes","label":"Yes"},{"id":"no","label":"No"},{"id":"unsure","label":"Not sure"}]},"causedByRequestId":"9d1f7a52-3c6e-4b85-8f0a-5b2c1d7e9a30","createdAt":"2026-10-18T15:04:40.000Z"}],"showCall911":false,"emergency":null,"duplicate":false}},"sentToTheTeam":{"summary":"A request sent straight to the team (when a guided leg can't run, or the workspace is paused)","value":{"conversation":{"id":"4a1c8e90-2b7d-4f36-9c05-7d3e1a6b8f12","patientId":"2c3d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f","externalConversationId":"portal-thread-991","channel":"portal_api","status":"open","careStatus":{"code":"received","label":"Received"},"appointment":null,"showCall911":false,"awaiting":{"type":"none"},"lastSequence":2,"version":3,"language":"en","safety":{"language":"en","emergencyLine":"If this is a medical emergency, call 911.","lines":[{"label":"Call 911","tel":"tel:911"}]},"createdAt":"2026-10-18T15:02:11.000Z","updatedAt":"2026-10-18T15:02:13.000Z"},"message":{"id":"9d1f7a52-3c6e-4b85-8f0a-5b2c1d7e9a30","sequence":1,"kind":"text","from":{"kind":"patient","label":"You"},"priority":"normal","language":"en","text":"My package hasn't arrived yet","createdAt":"2026-10-18T15:02:11.000Z"},"replies":[{"id":"a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d","sequence":2,"kind":"handoff","from":{"kind":"nezer","label":"NezerCare"},"priority":"normal","language":"en","text":"Thanks for reaching out — this has been sent to our fulfillment team and someone will follow up soon.","handoff":{"reference":"NC-AB12CD34","team":"fulfillment","urgency":"routine"},"causedByRequestId":"9d1f7a52-3c6e-4b85-8f0a-5b2c1d7e9a30","createdAt":"2026-10-18T15:04:40.000Z"}],"showCall911":false,"emergency":null,"duplicate":false}},"workflow":{"summary":"A request the clinic built a workflow for: its first question","value":{"conversation":{"id":"4a1c8e90-2b7d-4f36-9c05-7d3e1a6b8f12","patientId":"2c3d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f","externalConversationId":"portal-thread-991","channel":"portal_api","status":"open","careStatus":{"code":"received","label":"Received"},"appointment":null,"showCall911":false,"awaiting":{"type":"text","messageId":"c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f"},"lastSequence":2,"version":3,"language":"en","safety":{"language":"en","emergencyLine":"If this is a medical emergency, call 911.","lines":[{"label":"Call 911","tel":"tel:911"}]},"createdAt":"2026-10-18T15:02:11.000Z","updatedAt":"2026-10-18T15:02:13.000Z"},"message":{"id":"9d1f7a52-3c6e-4b85-8f0a-5b2c1d7e9a30","sequence":1,"kind":"text","from":{"kind":"patient","label":"You"},"priority":"normal","language":"en","text":"My order arrived damaged","createdAt":"2026-10-18T15:02:11.000Z"},"replies":[{"id":"c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f","sequence":2,"kind":"question","from":{"kind":"nezer","label":"NezerCare"},"priority":"normal","language":"en","text":"I'm sorry about that. What's the order number?","purpose":"workflow","input":{"type":"text","maxLength":2000},"causedByRequestId":"9d1f7a52-3c6e-4b85-8f0a-5b2c1d7e9a30","createdAt":"2026-10-18T15:05:20.000Z"}],"showCall911":false,"emergency":null,"duplicate":false}},"emergency":{"summary":"An emergency: the notice comes first","value":{"conversation":{"id":"4a1c8e90-2b7d-4f36-9c05-7d3e1a6b8f12","patientId":"2c3d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f","externalConversationId":"portal-thread-991","channel":"portal_api","status":"open","careStatus":{"code":"received","label":"Received"},"appointment":null,"showCall911":true,"awaiting":{"type":"none"},"lastSequence":2,"version":3,"language":"en","safety":{"language":"en","emergencyLine":"If this is a medical emergency, call 911.","lines":[{"label":"Call 911","tel":"tel:911"}]},"createdAt":"2026-10-18T15:02:11.000Z","updatedAt":"2026-10-18T15:02:13.000Z"},"message":{"id":"9d1f7a52-3c6e-4b85-8f0a-5b2c1d7e9a30","sequence":1,"kind":"text","from":{"kind":"patient","label":"You"},"priority":"normal","language":"en","text":"I have chest pain and I can't breathe","createdAt":"2026-10-18T15:02:11.000Z"},"replies":[{"id":"d4e5f6a7-b8c9-4d0e-9f2a-3b4c5d6e7f80","sequence":2,"kind":"emergency","from":{"kind":"nezer","label":"NezerCare"},"priority":"emergency","language":"en","text":"Call 911 now. What you described can need emergency care. Do not wait for your care team to reply.","emergency":{"lines":[{"label":"Call 911","tel":"tel:911"}],"sentToCareTeam":true},"causedByRequestId":"9d1f7a52-3c6e-4b85-8f0a-5b2c1d7e9a30","createdAt":"2026-10-18T15:09:30.000Z"}],"showCall911":true,"emergency":{"language":"en","message":"Call 911 now. What you described can need emergency care. Do not wait for your care team to reply.","lines":[{"label":"Call 911","tel":"tel:911"}]},"duplicate":false}}}}}},"400":{"description":"`INVALID_REQUEST`: a malformed body, or text over 10,000 characters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PortalError"},"example":{"code":"INVALID_REQUEST","message":"text must be longer than or equal to 1 characters"}}}},"401":{"description":"The API key is missing, invalid, expired or turned off.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PortalError"},"example":{"code":"INVALID_API_CREDENTIAL","message":"API credential is invalid."}}}},"403":{"description":"`BAA_REQUIRED` until the organization has signed its BAA (a NezerCare setup test key works before it), or `INSUFFICIENT_SCOPE` when the key doesn't have the `portal_messaging` scope. Don't retry either; tell the patient the message was not sent and keep the 911 line in view.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PortalError"},"example":{"code":"INSUFFICIENT_SCOPE","message":"This API key doesn't have the portal_messaging scope. Create a key with it in Integrations, API keys."}}}},"404":{"description":"`PATIENT_NOT_FOUND`: no such patient in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PortalError"},"example":{"code":"PATIENT_NOT_FOUND","message":"No patient with this ID in this workspace."}}}},"409":{"description":"`REQUEST_ID_REUSED` (the `requestId` was used for different words), `TURN_IN_PROGRESS` (another message is still being handled: wait for `Retry-After`, then retry with the same `requestId`), `EXTERNAL_CONVERSATION_ID_IN_USE`, or `PATIENT_INACTIVE` (an emergency is still taken and the body carries `showCall911` and `emergency`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PortalError"},"example":{"code":"REQUEST_ID_REUSED","message":"This requestId was already used for a different message. Use a new requestId for a new message."}}}},"429":{"description":"`RATE_LIMITED`: this patient is sending faster than 20 messages a minute, or this API key has sent more than it may (an API key may send 600 requests a minute and 20,000 an hour, on any route it can call (this API, the conversation gateway and the care hand-off), and start 60 new conversations a minute and 1,000 an hour). **Never an emergency:** an emergency message is not counted, refused or charged by any of these limits (it has a ceiling on what is *stored* of its own, below). Honor `Retry-After`, then retry with the same `requestId`; tell the patient the message was not sent and keep the 911 line in view.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PortalError"},"example":{"code":"RATE_LIMITED","message":"This patient is sending messages faster than allowed. Wait, then retry with the same requestId."}}}},"500":{"description":"A failure on NezerCare's side. Retry with the same `requestId` and backoff: a turn that stopped part way is finished by the retry, and the message is never sent to the team twice. If it keeps failing, tell the patient the message was not received and keep the 911 line in view. When the message was an emergency, the body still carries `showCall911` and `emergency`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PortalError"},"example":{"code":"INTERNAL_ERROR","message":"The message could not be handled. Retry with the same requestId."}}}}}}},"/v1/patients/{patientId}/conversations/{conversationId}":{"get":{"tags":["Patient messaging"],"operationId":"getPatientConversation","summary":"Read one conversation","description":"One conversation's state, never stale: it first brings the conversation up to date with what the care team has written, as reading the messages does, so a `careStatus` of \"New reply from your care team\" is there as soon as the reply is. The same object a turn returns, with the `safety` words to print. A conversation that isn't this patient's, or isn't in your workspace, is `404`.","security":[{"bearerAuth":[]}],"parameters":[{"name":"patientId","in":"path","required":true,"description":"The patient's NezerCare ID, from `POST /v1/patients/identify`. Another workspace's patient, or one that isn't this conversation's, is `404`.","schema":{"type":"string","format":"uuid"}},{"name":"conversationId","in":"path","required":true,"description":"The conversation's ID, from the response that started it.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The conversation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PortalConversation"},"example":{"id":"4a1c8e90-2b7d-4f36-9c05-7d3e1a6b8f12","patientId":"2c3d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f","externalConversationId":"portal-thread-991","channel":"portal_api","status":"open","careStatus":{"code":"replied","label":"New reply from your care team"},"appointment":null,"showCall911":false,"awaiting":{"type":"none"},"lastSequence":3,"version":4,"language":"en","safety":{"language":"en","emergencyLine":"If this is a medical emergency, call 911.","lines":[{"label":"Call 911","tel":"tel:911"}]},"createdAt":"2026-10-18T15:02:11.000Z","updatedAt":"2026-10-18T15:02:13.000Z"}}}},"401":{"description":"The API key is missing, invalid, expired or turned off.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PortalError"},"example":{"code":"INVALID_API_CREDENTIAL","message":"API credential is invalid."}}}},"403":{"description":"`BAA_REQUIRED` until the organization has signed its BAA (a NezerCare setup test key works before it), or `INSUFFICIENT_SCOPE` when the key doesn't have the `portal_messaging` scope. Don't retry either; tell the patient the message was not sent and keep the 911 line in view.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PortalError"},"example":{"code":"INSUFFICIENT_SCOPE","message":"This API key doesn't have the portal_messaging scope. Create a key with it in Integrations, API keys."}}}},"404":{"description":"`CONVERSATION_NOT_FOUND`: not this patient's conversation, or another workspace's.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PortalError"},"example":{"code":"CONVERSATION_NOT_FOUND","message":"No conversation with this ID for this patient."}}}},"429":{"description":"`RATE_LIMITED`: this API key has sent more requests than it may (an API key may send 600 requests a minute and 20,000 an hour, on any route it can call (this API, the conversation gateway and the care hand-off), and start 60 new conversations a minute and 1,000 an hour). Honor `Retry-After`, then retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PortalError"},"example":{"code":"RATE_LIMITED","message":"This API key is sending requests faster than allowed (600 a minute). Wait for Retry-After, then retry with the same requestId."}}}}}}},"/v1/patients/{patientId}/conversations/{conversationId}/messages/{messageId}/delivery":{"post":{"tags":["Patient messaging"],"operationId":"recordPortalDelivery","summary":"Report that a message was shown","description":"Tell NezerCare what your screen did with a message it was sent: `delivered` (shown), `read` (the patient read it) or `failed` (it could not be shown). Each status is recorded once per message; a repeat is ignored (`200`, `duplicate: true`).\n\nA **`failed`** report opens a high-priority work item for the care team (\"External delivery failed\", in the Integration queue of Operations), once per message, so a person looks into it. For an **emergency notice** the work item is urgent: report it the moment your screen could not show the 911 notice, so the clinic can reach the patient another way. `errorCode` is a short machine word (letters, digits and `_ . : -`, up to 80): never the patient's or the care team's words. Only a message NezerCare or the care team sent can have a receipt, not the patient's own.\n\n**Confirm every 911 notice.** Report `delivered` the moment your screen shows an emergency notice. A notice with no receipt of any kind two minutes after it was sent opens an urgent work item for the care team (\"Emergency notice not confirmed\", in the Integration queue of Operations, due within 15 minutes) so a person can reach the patient another way; notices of one conversation within 15 minutes share one item. A portal that sends no receipts at all gets an item for every emergency, up to 20 an hour for a key; past that one summary item (\"Many emergency notices not confirmed\") covers the rest.","security":[{"bearerAuth":[]}],"parameters":[{"name":"patientId","in":"path","required":true,"description":"The patient's NezerCare ID, from `POST /v1/patients/identify`. Another workspace's patient, or one that isn't this conversation's, is `404`.","schema":{"type":"string","format":"uuid"}},{"name":"conversationId","in":"path","required":true,"description":"The conversation's ID, from the response that started it.","schema":{"type":"string","format":"uuid"}},{"name":"messageId","in":"path","required":true,"description":"The ID of the message the receipt is for.","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PortalDeliveryRequest"},"examples":{"delivered":{"summary":"Shown on the screen","value":{"status":"delivered"}},"failed":{"summary":"Could not be shown","value":{"status":"failed","errorCode":"render_error"}}}}}},"responses":{"200":{"description":"This status was already recorded for the message; nothing changed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PortalDeliveryResponse"},"example":{"conversationId":"4a1c8e90-2b7d-4f36-9c05-7d3e1a6b8f12","messageId":"e6f4b7c2-91a0-4d38-8b5e-3c7a2d9f1e04","status":"delivered","duplicate":true,"recordedAt":"2026-10-18T15:02:14.000Z"}}}},"201":{"description":"Recorded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PortalDeliveryResponse"},"example":{"conversationId":"4a1c8e90-2b7d-4f36-9c05-7d3e1a6b8f12","messageId":"e6f4b7c2-91a0-4d38-8b5e-3c7a2d9f1e04","status":"failed","duplicate":false,"recordedAt":"2026-10-18T15:02:14.000Z"}}}},"400":{"description":"`INVALID_REQUEST`: an unknown status, an `errorCode` that isn't a short machine word or comes with a status other than `failed`, or a receipt for the patient's own message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PortalError"},"example":{"code":"INVALID_REQUEST","message":"errorCode goes with a failed receipt only."}}}},"401":{"description":"The API key is missing, invalid, expired or turned off.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PortalError"},"example":{"code":"INVALID_API_CREDENTIAL","message":"API credential is invalid."}}}},"403":{"description":"`BAA_REQUIRED` until the organization has signed its BAA (a NezerCare setup test key works before it), or `INSUFFICIENT_SCOPE` when the key doesn't have the `portal_messaging` scope. Don't retry either; tell the patient the message was not sent and keep the 911 line in view.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PortalError"},"example":{"code":"INSUFFICIENT_SCOPE","message":"This API key doesn't have the portal_messaging scope. Create a key with it in Integrations, API keys."}}}},"404":{"description":"`CONVERSATION_NOT_FOUND` (not this patient's, or another workspace's) or `MESSAGE_NOT_FOUND` (not a message of this conversation).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PortalError"},"example":{"code":"MESSAGE_NOT_FOUND","message":"No message with this ID in this conversation."}}}},"429":{"description":"`RATE_LIMITED`: this API key has sent more requests than it may (an API key may send 600 requests a minute and 20,000 an hour, on any route it can call (this API, the conversation gateway and the care hand-off), and start 60 new conversations a minute and 1,000 an hour). Honor `Retry-After`, then retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PortalError"},"example":{"code":"RATE_LIMITED","message":"This API key is sending requests faster than allowed (600 a minute). Wait for Retry-After, then retry with the same requestId."}}}}}}},"/v1/patients/{patientId}/conversations/{conversationId}/messages":{"post":{"tags":["Patient messaging"],"operationId":"sendPatientMessage","summary":"Send the patient's next message","description":"The patient's next message in a conversation, or a button they pressed: exactly one of `text` and `choiceId`. A `choiceId` is one of the buttons the message it is under offers, and needs `inReplyTo`, that message's ID: `helpful` (\"Yes, thanks\", recorded) and `talk_to_team` (sends the question the answer was for to the team) under a knowledge answer; `yes`, `no` and `unsure` under a safety check; `send` under \"Does this look right?\"; `send_now` under the shortcut of an urgent concern; `yes` and `no` under a workflow's confirmation; `done` and `skip` under its request for photos (add the files first, with the attachments call, and list them in `attachments`); `talk_to_team` under a finished workflow run's offer of a person. A button on a message that is not the latest, or that doesn't offer it, is `409 STALE_ANSWER`. A patient may always type instead: a correction to a review, or words for a question.\n\nReturns when NezerCare's replies to this message are ready, in the response: allow up to 60 seconds. The patient's `message` is first, then `replies` (NezerCare's messages, in sequence order).\n\n**The emergency check runs first on every message**, by the same fixed rule the widget uses and the clinic's own extra emergency phrases. No AI, no credits, no limit, and it works while the workspace is paused. A match is filed with the care team as an emergency case, and the response carries `showCall911: true` and `emergency` at the top, with the emergency notice as `replies[0]` (`kind: \"emergency\"`, `priority: \"emergency\"`, the lowest sequence of the turn). **Show it at once, in full, and never hide, delay or rewrite it.** An error response to a message that was an emergency carries the same two fields.\n\nIf an emergency can't be filed with the care team on the first try, the notice is shown all the same (`emergency.sentToCareTeam: false`, the same words) and NezerCare keeps trying until it is filed.\n\nOtherwise the message is handled like the widget handles it:\n\n- A **health concern** starts the Health concerns questions: the safety checks as written and the clinic's approved questions (`kind: \"question\"`, answered by a button or in words), then \"Does this look right?\" (`kind: \"review\"`) with a summary of the patient's own words. Pressing `send` puts it with the care team (`kind: \"handoff\"`); typing instead is a correction. A health question is **never** answered by AI. An urgent concern lets the patient send at once (`send_now`), and one the patient walks away from is filed for them after ten minutes: the next read of the conversation carries the `handoff`.\n- A **billing, scheduling, fulfillment or support request** starts a short guided chat the same way (`question`, `review`, `handoff`).\n- A request the clinic built a **workflow** for runs it: its replies as `text`, an order lookup's orders as `orders`, and what it needs next as a `question` (words, a yes or no, or photos). A run that ends offers the care team (`talk_to_team`).\n- An **everyday business question** is answered from the clinic's own knowledge with its sources (`kind: \"answer\"`, one credit).\n- A message in a conversation the team already has goes into that thread, with no reply from NezerCare.\n\nIf a guided leg can't run (the clinic's intake is switched off), the message goes straight to the right team (`kind: \"handoff\"`). While the workspace is paused (trial ended, or out of credits) the Health concerns questions run with no AI, and anything else goes to the team with a `notice` that replies may be delayed; nothing is charged.\n\nEach model turn of the Health concerns questions or the guided chat is one credit; a workflow run that finishes is two; and a request that reaches the billing, scheduling, fulfillment or support team is opened as a case in Operations, which is two. The patient's message, the emergency notice and sending a health concern to the care team are free, and while the workspace is paused nothing is charged.\n\n**Limits on your API key.** Past a limit on requests or on new conversations (`429 RATE_LIMITED`, see below), a message is refused and the patient should be told it was not sent, but an emergency is never refused. Each API key also has a number of credits it may use a day (500 unless the workspace chose another number, in Integrations, Patient messaging). Past that, the key's messages are **not** refused: they run as a paused workspace's do (no AI reply, nothing charged, every message goes to the care team with a `notice` that replies may be delayed) until the day starts again at midnight UTC.\n\n**Emergencies and what they store.** An emergency is always answered first with the notice, and never refused. But a key that sends hundreds of emergency messages an hour is not a patient in trouble, so NezerCare stores up to 300 emergency messages an hour for a key in full. Past that, a patient whose emergency the care team already has (an unresolved emergency case of theirs from the last 15 minutes) is still answered at once with the 911 notice (`showCall911: true`, `emergency.sentToCareTeam: true`, `duplicate: true`), but **that repeat is not stored**: it is not in the conversation's feed, and the response's `message` and notice are not kept. A different patient, or the same one after the 15 minutes, is filed and stored as always. Always show the notice from the response; do not wait for it to appear in the feed.\n\nSend the same `requestId` to retry: the stored turn comes back (`duplicate: true`), nothing is charged or sent twice, and the same ID with different words is `409 REQUEST_ID_REUSED`. A turn that stopped part way is finished by the retry: the questions are not answered twice and the team is not sent the message twice.\n\nA closed conversation (the care team resolved or closed it) refuses a message with `409 CONVERSATION_CLOSED`, except an emergency, which is always taken and reopens it.","security":[{"bearerAuth":[]}],"parameters":[{"name":"patientId","in":"path","required":true,"description":"The patient's NezerCare ID, from `POST /v1/patients/identify`. Another workspace's patient, or one that isn't this conversation's, is `404`.","schema":{"type":"string","format":"uuid"}},{"name":"conversationId","in":"path","required":true,"description":"The conversation's ID, from the response that started it.","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatientMessageRequest"},"examples":{"text":{"summary":"The patient typed","value":{"requestId":"3f8e2a10-6b4c-4d7a-9e15-8c0b7a2d4e61","text":"Do you ship internationally?"}},"button":{"summary":"The patient pressed a button under a knowledge answer","value":{"requestId":"6c1d9e47-2f03-4a58-b7e6-0d4a8c3f5b92","choiceId":"talk_to_team","inReplyTo":"e6f4b7c2-91a0-4d38-8b5e-3c7a2d9f1e04"}},"safetyCheck":{"summary":"The patient answered a safety check","value":{"requestId":"3f8e2a10-6b4c-4d7a-9e15-8c0b7a2d4e61","choiceId":"no","inReplyTo":"b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e"}},"send":{"summary":"The patient sent the reviewed summary to the care team","value":{"requestId":"7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d","choiceId":"send","inReplyTo":"c3d4e5f6-a7b8-4c9d-8e1f-2a3b4c5d6e7f"}},"photos":{"summary":"The patient added photos (see Add a photo or PDF) and pressed Done","value":{"requestId":"8b9c0d1e-2f3a-4b4c-9d5e-6f7a8b9c0d1e","choiceId":"done","inReplyTo":"d7e8f9a0-b1c2-4d3e-9f4a-5b6c7d8e9f01","attachments":[{"id":"a0b1c2d3-e4f5-4a6b-8c7d-9e0f1a2b3c4d"}]}}}}}},"responses":{"201":{"description":"The patient's message and NezerCare's replies (none, when the message went into a thread the care team already has).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatientTurnResponse"},"examples":{"intoTheTeamsThread":{"summary":"A message in a conversation the care team has: no reply from NezerCare","value":{"conversation":{"id":"4a1c8e90-2b7d-4f36-9c05-7d3e1a6b8f12","patientId":"2c3d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f","externalConversationId":"portal-thread-991","channel":"portal_api","status":"open","careStatus":{"code":"received","label":"Received"},"appointment":null,"showCall911":false,"awaiting":{"type":"none"},"lastSequence":4,"version":5,"language":"en","safety":{"language":"en","emergencyLine":"If this is a medical emergency, call 911.","lines":[{"label":"Call 911","tel":"tel:911"}]},"createdAt":"2026-10-18T15:02:11.000Z","updatedAt":"2026-10-18T15:02:13.000Z"},"message":{"id":"9d1f7a52-3c6e-4b85-8f0a-5b2c1d7e9a30","sequence":3,"kind":"text","from":{"kind":"patient","label":"You"},"priority":"normal","language":"en","text":"Do you ship internationally?","createdAt":"2026-10-18T15:02:11.000Z"},"replies":[],"showCall911":false,"emergency":null,"duplicate":false}},"question":{"summary":"An approved question of the Health concerns intake","value":{"conversation":{"id":"4a1c8e90-2b7d-4f36-9c05-7d3e1a6b8f12","patientId":"2c3d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f","externalConversationId":"portal-thread-991","channel":"portal_api","status":"open","careStatus":{"code":"received","label":"Received"},"appointment":null,"showCall911":false,"awaiting":{"type":"text","messageId":"c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f"},"lastSequence":7,"version":8,"language":"en","safety":{"language":"en","emergencyLine":"If this is a medical emergency, call 911.","lines":[{"label":"Call 911","tel":"tel:911"}]},"createdAt":"2026-10-18T15:02:11.000Z","updatedAt":"2026-10-18T15:02:13.000Z"},"message":{"id":"3f8e2a10-6b4c-4d7a-9e15-8c0b7a2d4e61","sequence":6,"kind":"text","from":{"kind":"patient","label":"You"},"priority":"normal","language":"en","text":"No","createdAt":"2026-10-18T15:02:11.000Z"},"replies":[{"id":"c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f","sequence":7,"kind":"question","from":{"kind":"nezer","label":"NezerCare"},"priority":"normal","language":"en","text":"When did it start?","purpose":"intake","input":{"type":"text","maxLength":2000},"causedByRequestId":"9d1f7a52-3c6e-4b85-8f0a-5b2c1d7e9a30","createdAt":"2026-10-18T15:05:20.000Z"}],"showCall911":false,"emergency":null,"duplicate":false}},"review":{"summary":"\"Does this look right?\": the summary, built from the patient's own words","value":{"conversation":{"id":"4a1c8e90-2b7d-4f36-9c05-7d3e1a6b8f12","patientId":"2c3d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f","externalConversationId":"portal-thread-991","channel":"portal_api","status":"open","careStatus":{"code":"received","label":"Received"},"appointment":null,"showCall911":false,"awaiting":{"type":"choice","messageId":"c3d4e5f6-a7b8-4c9d-8e1f-2a3b4c5d6e7f","choices":["send"]},"lastSequence":9,"version":10,"language":"en","safety":{"language":"en","emergencyLine":"If this is a medical emergency, call 911.","lines":[{"label":"Call 911","tel":"tel:911"}]},"createdAt":"2026-10-18T15:02:11.000Z","updatedAt":"2026-10-18T15:02:13.000Z"},"message":{"id":"9d1f7a52-3c6e-4b85-8f0a-5b2c1d7e9a30","sequence":8,"kind":"text","from":{"kind":"patient","label":"You"},"priority":"normal","language":"en","text":"It started two days ago","createdAt":"2026-10-18T15:02:11.000Z"},"replies":[{"id":"c3d4e5f6-a7b8-4c9d-8e1f-2a3b4c5d6e7f","sequence":9,"kind":"review","from":{"kind":"nezer","label":"NezerCare"},"priority":"normal","language":"en","text":"Does this look right?","status":"ready","summary":"Here's what I understood:\n\nConcern: a reddish spot on my arm\n\nAdditional details: It started two days ago","choices":[{"id":"send","label":"Yes, send it"}],"input":{"type":"text","maxLength":2000,"hint":"Need to change something?"},"causedByRequestId":"9d1f7a52-3c6e-4b85-8f0a-5b2c1d7e9a30","createdAt":"2026-10-18T15:07:02.000Z"}],"showCall911":false,"emergency":null,"duplicate":false}},"sent":{"summary":"Sent: the care team has it","value":{"conversation":{"id":"4a1c8e90-2b7d-4f36-9c05-7d3e1a6b8f12","patientId":"2c3d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f","externalConversationId":"portal-thread-991","channel":"portal_api","status":"open","careStatus":{"code":"received","label":"Received"},"appointment":null,"showCall911":false,"awaiting":{"type":"none"},"lastSequence":11,"version":12,"language":"en","safety":{"language":"en","emergencyLine":"If this is a medical emergency, call 911.","lines":[{"label":"Call 911","tel":"tel:911"}]},"createdAt":"2026-10-18T15:02:11.000Z","updatedAt":"2026-10-18T15:02:13.000Z"},"message":{"id":"7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d","sequence":10,"kind":"text","from":{"kind":"patient","label":"You"},"priority":"normal","language":"en","text":"Yes, send it","createdAt":"2026-10-18T15:02:11.000Z"},"replies":[{"id":"a9b8c7d6-e5f4-4a3b-8c2d-1e0f9a8b7c6d","sequence":11,"kind":"handoff","from":{"kind":"nezer","label":"NezerCare"},"priority":"normal","language":"en","text":"Sent to your care team. Your care team has your update.","handoff":{"reference":"NC-AB12CD34","team":"clinical","urgency":"routine"},"causedByRequestId":"9d1f7a52-3c6e-4b85-8f0a-5b2c1d7e9a30","createdAt":"2026-10-18T15:08:15.000Z"}],"showCall911":false,"emergency":null,"duplicate":false}},"photosAsked":{"summary":"A workflow asks for photos","value":{"conversation":{"id":"4a1c8e90-2b7d-4f36-9c05-7d3e1a6b8f12","patientId":"2c3d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f","externalConversationId":"portal-thread-991","channel":"portal_api","status":"open","careStatus":{"code":"received","label":"Received"},"appointment":null,"showCall911":false,"awaiting":{"type":"attachments","messageId":"d7e8f9a0-b1c2-4d3e-9f4a-5b6c7d8e9f01","choices":["done","skip"]},"lastSequence":4,"version":3,"language":"en","safety":{"language":"en","emergencyLine":"If this is a medical emergency, call 911.","lines":[{"label":"Call 911","tel":"tel:911"}]},"createdAt":"2026-10-18T15:02:11.000Z","updatedAt":"2026-10-18T15:02:13.000Z"},"message":{"id":"9d1f7a52-3c6e-4b85-8f0a-5b2c1d7e9a30","sequence":3,"kind":"text","from":{"kind":"patient","label":"You"},"priority":"normal","language":"en","text":"A10001","createdAt":"2026-10-18T15:02:11.000Z"},"replies":[{"id":"d7e8f9a0-b1c2-4d3e-9f4a-5b6c7d8e9f01","sequence":4,"kind":"question","from":{"kind":"nezer","label":"NezerCare"},"priority":"normal","language":"en","text":"Could you add a photo or two of what arrived?","purpose":"workflow","input":{"type":"attachments"},"choices":[{"id":"done","label":"Done"},{"id":"skip","label":"I don't have any"}],"causedByRequestId":"9d1f7a52-3c6e-4b85-8f0a-5b2c1d7e9a30","createdAt":"2026-10-18T15:05:40.000Z"}],"showCall911":false,"emergency":null,"duplicate":false}},"orders":{"summary":"An order lookup's orders, then the offer of a person","value":{"conversation":{"id":"4a1c8e90-2b7d-4f36-9c05-7d3e1a6b8f12","patientId":"2c3d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f","externalConversationId":"portal-thread-991","channel":"portal_api","status":"open","careStatus":{"code":"received","label":"Received"},"appointment":null,"showCall911":false,"awaiting":{"type":"choice","messageId":"f2a3b4c5-d6e7-4f8a-9b0c-1d2e3f4a5b6c","choices":["talk_to_team"]},"lastSequence":4,"version":3,"language":"en","safety":{"language":"en","emergencyLine":"If this is a medical emergency, call 911.","lines":[{"label":"Call 911","tel":"tel:911"}]},"createdAt":"2026-10-18T15:02:11.000Z","updatedAt":"2026-10-18T15:02:13.000Z"},"message":{"id":"9d1f7a52-3c6e-4b85-8f0a-5b2c1d7e9a30","sequence":1,"kind":"text","from":{"kind":"patient","label":"You"},"priority":"normal","language":"en","text":"Where is my order?","createdAt":"2026-10-18T15:02:11.000Z"},"replies":[{"id":"e0f1a2b3-c4d5-4e6f-8a7b-9c0d1e2f3a4b","sequence":3,"kind":"orders","from":{"kind":"nezer","label":"NezerCare"},"priority":"normal","language":"en","text":"Order R-10482: Shipped · With UPS · Expected 2026-10-21 · 2 × Test Product","orders":[{"id":"R-10482","status":"shipped","statusLabel":null,"carrier":"UPS","trackingUrl":"https://www.ups.com/track?tracknum=1Z999","estimatedDelivery":"2026-10-21","placedAt":"2026-10-15T14:00:00Z","items":[{"name":"Test Product","quantity":2}]}],"causedByRequestId":"9d1f7a52-3c6e-4b85-8f0a-5b2c1d7e9a30","createdAt":"2026-10-18T15:06:00.000Z"},{"id":"f2a3b4c5-d6e7-4f8a-9b0c-1d2e3f4a5b6c","sequence":4,"kind":"question","from":{"kind":"nezer","label":"NezerCare"},"priority":"normal","language":"en","text":"Anything else we can help with?","purpose":"workflow","input":{"type":"choice","choices":[{"id":"talk_to_team","label":"Talk to the team"}]},"causedByRequestId":"9d1f7a52-3c6e-4b85-8f0a-5b2c1d7e9a30","createdAt":"2026-10-18T15:06:01.000Z"}],"showCall911":false,"emergency":null,"duplicate":false}}}}}},"400":{"description":"`INVALID_REQUEST`: both or neither of `text` and `choiceId`, a `choiceId` without `inReplyTo`, or a malformed body.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PortalError"},"example":{"code":"INVALID_REQUEST","message":"Send exactly one of text and choiceId."}}}},"401":{"description":"The API key is missing, invalid, expired or turned off.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PortalError"},"example":{"code":"INVALID_API_CREDENTIAL","message":"API credential is invalid."}}}},"403":{"description":"`BAA_REQUIRED` until the organization has signed its BAA (a NezerCare setup test key works before it), or `INSUFFICIENT_SCOPE` when the key doesn't have the `portal_messaging` scope. Don't retry either; tell the patient the message was not sent and keep the 911 line in view.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PortalError"},"example":{"code":"INSUFFICIENT_SCOPE","message":"This API key doesn't have the portal_messaging scope. Create a key with it in Integrations, API keys."}}}},"404":{"description":"`PATIENT_NOT_FOUND`, `CONVERSATION_NOT_FOUND` (not this patient's, or another workspace's), `MESSAGE_NOT_FOUND`, or `ATTACHMENT_NOT_FOUND` (a listed file isn't one this patient added to this conversation, or was deleted since).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PortalError"},"example":{"code":"CONVERSATION_NOT_FOUND","message":"No conversation with this ID for this patient."}}}},"409":{"description":"`REQUEST_ID_REUSED`, `TURN_IN_PROGRESS`, `CONVERSATION_CLOSED`, `STALE_ANSWER` or `PATIENT_INACTIVE`. An error to an emergency message carries `showCall911` and `emergency`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PortalError"},"example":{"code":"CONVERSATION_CLOSED","message":"This conversation is closed. Start a new conversation.","showCall911":true,"emergency":{"language":"en","message":"Call 911 now. What you described can need emergency care. Do not wait for your care team to reply.","lines":[{"label":"Call 911","tel":"tel:911"}]}}}}},"429":{"description":"`RATE_LIMITED`: this patient is sending faster than 20 messages a minute, or this API key has sent more than it may (an API key may send 600 requests a minute and 20,000 an hour, on any route it can call (this API, the conversation gateway and the care hand-off), and start 60 new conversations a minute and 1,000 an hour). **Never an emergency:** an emergency message is not counted, refused or charged by any of these limits (it has a ceiling on what is *stored* of its own, below). Honor `Retry-After`, then retry with the same `requestId`; tell the patient the message was not sent and keep the 911 line in view.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PortalError"},"example":{"code":"RATE_LIMITED","message":"This patient is sending messages faster than allowed. Wait, then retry with the same requestId."}}}},"500":{"description":"A failure on NezerCare's side. Retry with the same `requestId` and backoff: a turn that stopped part way is finished by the retry, and the message is never sent to the team twice. If it keeps failing, tell the patient the message was not received and keep the 911 line in view. When the message was an emergency, the body still carries `showCall911` and `emergency`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PortalError"},"example":{"code":"INTERNAL_ERROR","message":"The message could not be handled. Retry with the same requestId."}}}}}},"get":{"tags":["Patient messaging"],"operationId":"listPatientMessages","summary":"Read the conversation","description":"The conversation's ordered feed after a sequence: the patient's messages, NezerCare's and the care team's. Call it when the screen opens, when the app returns to the foreground, and on a timer while it's open: it is how the care team's replies reach the screen. It first brings the feed up to date with what the care team has written, so a read is never stale; a reply from the care team appears once, as `from.kind: \"care_team\"` labelled `Care team` (never a name). Internal notes, resolution notes and anything staff-only are never in it. When the care team resolves the case or closes the conversation, a `closed` message arrives and `conversation.status` is `closed`. Apply messages by `sequence`, not by arrival.\n\nThe same messages also arrive by signed webhook (`conversation.message_created`) within a second or two, for speed; this call is the truth. Webhooks are delivered at least once, in parallel and in no promised order, and a delivery can give up: when a message's `sequence` is more than one above the last you have, or when the screen opens, read this feed after the last sequence you have.","security":[{"bearerAuth":[]}],"parameters":[{"name":"patientId","in":"path","required":true,"description":"The patient's NezerCare ID, from `POST /v1/patients/identify`. Another workspace's patient, or one that isn't this conversation's, is `404`.","schema":{"type":"string","format":"uuid"}},{"name":"conversationId","in":"path","required":true,"description":"The conversation's ID, from the response that started it.","schema":{"type":"string","format":"uuid"}},{"name":"afterSequence","in":"query","required":false,"description":"The last sequence you have; the default is 0 (everything).","schema":{"type":"integer","minimum":0,"default":0}},{"name":"limit","in":"query","required":false,"description":"At most this many messages (up to 250).","schema":{"type":"integer","minimum":1,"maximum":250,"default":100}}],"responses":{"200":{"description":"Messages after `afterSequence`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PortalMessageList"},"examples":{"careTeamReply":{"summary":"A care team reply","value":{"messages":[{"id":"e5f6a7b8-c9d0-4e1f-8a3b-4c5d6e7f8091","sequence":3,"kind":"text","from":{"kind":"care_team","label":"Care team"},"priority":"normal","language":"en","text":"Please keep the spot clean and dry. A nurse will call you today.","createdAt":"2026-10-18T16:21:44.000Z"}],"lastSequence":3,"hasMore":false,"conversation":{"id":"4a1c8e90-2b7d-4f36-9c05-7d3e1a6b8f12","patientId":"2c3d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f","externalConversationId":"portal-thread-991","channel":"portal_api","status":"open","careStatus":{"code":"replied","label":"New reply from your care team"},"appointment":null,"showCall911":false,"awaiting":{"type":"none"},"lastSequence":3,"version":4,"language":"en","safety":{"language":"en","emergencyLine":"If this is a medical emergency, call 911.","lines":[{"label":"Call 911","tel":"tel:911"}]},"createdAt":"2026-10-18T15:02:11.000Z","updatedAt":"2026-10-18T15:02:13.000Z"}}},"closed":{"summary":"The conversation closed","value":{"messages":[{"id":"f6a7b8c9-d0e1-4f2a-9b4c-5d6e7f809102","sequence":4,"kind":"closed","from":{"kind":"nezer","label":"NezerCare"},"priority":"normal","language":"en","text":"Closed","closed":{"reason":"closed"},"createdAt":"2026-10-18T17:02:00.000Z"}],"lastSequence":4,"hasMore":false,"conversation":{"id":"4a1c8e90-2b7d-4f36-9c05-7d3e1a6b8f12","patientId":"2c3d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f","externalConversationId":"portal-thread-991","channel":"portal_api","status":"closed","careStatus":{"code":"closed","label":"Closed"},"appointment":null,"showCall911":false,"awaiting":{"type":"none"},"lastSequence":4,"version":5,"language":"en","safety":{"language":"en","emergencyLine":"If this is a medical emergency, call 911.","lines":[{"label":"Call 911","tel":"tel:911"}]},"createdAt":"2026-10-18T15:02:11.000Z","updatedAt":"2026-10-18T15:02:13.000Z"}}}}}}},"400":{"description":"`INVALID_REQUEST`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PortalError"},"example":{"code":"INVALID_REQUEST","message":"afterSequence must not be less than 0"}}}},"401":{"description":"The API key is missing, invalid, expired or turned off.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PortalError"},"example":{"code":"INVALID_API_CREDENTIAL","message":"API credential is invalid."}}}},"403":{"description":"`BAA_REQUIRED` until the organization has signed its BAA (a NezerCare setup test key works before it), or `INSUFFICIENT_SCOPE` when the key doesn't have the `portal_messaging` scope. Don't retry either; tell the patient the message was not sent and keep the 911 line in view.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PortalError"},"example":{"code":"INSUFFICIENT_SCOPE","message":"This API key doesn't have the portal_messaging scope. Create a key with it in Integrations, API keys."}}}},"404":{"description":"`CONVERSATION_NOT_FOUND`: not this patient's conversation, or another workspace's.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PortalError"},"example":{"code":"CONVERSATION_NOT_FOUND","message":"No conversation with this ID for this patient."}}}},"429":{"description":"`RATE_LIMITED`: this API key has sent more requests than it may (an API key may send 600 requests a minute and 20,000 an hour, on any route it can call (this API, the conversation gateway and the care hand-off), and start 60 new conversations a minute and 1,000 an hour). Honor `Retry-After`, then retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PortalError"},"example":{"code":"RATE_LIMITED","message":"This API key is sending requests faster than allowed (600 a minute). Wait for Retry-After, then retry with the same requestId."}}}}}}},"/v1/clinical-cases/{caseId}/progress":{"get":{"tags":["Clinical cases"],"operationId":"getClinicalCaseProgress","summary":"Read current external-care progress","description":"Needs a key with the `care_handoff` scope. Use this endpoint to reconcile sequence conflicts and confirm the next accepted sequence. Transport delivery and provider processing are intentionally separate fields. It shows the case as it stands now, however it got there: a team member's resolution in NezerCare shows here as `resolved`.","parameters":[{"name":"caseId","in":"path","required":true,"description":"The canonical UUID from the clinical_case.opened webhook. This is not the patient-facing NC-XXXXXXXX reference.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Current progress.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CaseProgress"},"example":{"caseId":"150d31aa-c9ed-4624-b516-8f7f354f0848","status":"awaiting_processing","sequence":0,"confirmationOverdue":false,"confirmationDueAt":"2026-10-11T14:20:00.000Z","transportDelivered":true,"scheduledFor":null,"hasVisitLink":false,"updatedAt":"2026-10-11T14:05:00.000Z","externalReference":null,"nextSequence":1}}}},"400":{"description":"The request is malformed or breaks the operation's contract: a field of the wrong type or outside its limits, a field the operation doesn't take (unknown fields are refused, not ignored), or an ID that isn't a UUID. `message` is a sentence, or a list of sentences, one for each field that failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"message":["resolutionNote must be longer than or equal to 10 characters"],"error":"Bad Request","statusCode":400}}}},"401":{"description":"`MISSING_API_CREDENTIAL`: no bearer key was sent. `INVALID_API_CREDENTIAL`: the key is invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing":{"summary":"No key sent","value":{"code":"MISSING_API_CREDENTIAL","message":"A bearer API credential is required."}},"invalid":{"summary":"Invalid, expired or revoked key","value":{"code":"INVALID_API_CREDENTIAL","message":"API credential is invalid."}}}}}},"403":{"description":"`BAA_REQUIRED`: the organization hasn't signed its BAA, so patient features (and API keys) are off. An owner or administrator signs it in Settings; it takes effect within about half a minute. `INSUFFICIENT_SCOPE`: the key wasn't made for this route (see the scope in the operation's description); make a new key with the scope, as a key never gains one later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"baaRequired":{"summary":"BAA not signed","value":{"code":"BAA_REQUIRED","message":"Sign your BAA to turn on patient features. An owner or administrator can sign it in Settings."}},"insufficientScope":{"summary":"The key lacks the scope","value":{"code":"INSUFFICIENT_SCOPE","message":"This API key doesn't have the care_handoff scope. Create a key with it in Integrations, API keys."}}}}}},"404":{"description":"No case with this ID in the key's organization. Another organization's case and one that never existed look the same.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"message":"Case not found.","error":"Not Found","statusCode":404}}}},"409":{"description":"A conflict; the body says which. A `updateId` or `messageId` reused with different content. An update out of sequence (the body carries `nextSequence`), a first update that isn't `processed`, or an update to a case that is already resolved. Or (code `ENVIRONMENT_RETIRED`) the API key belongs to an earlier copy of the organization's workspace that was retired in October 2026: every request with it is refused; create a new key in the workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"outOfSequence":{"summary":"An update out of sequence","value":{"message":"Update out of sequence.","nextSequence":2}},"idReused":{"summary":"An ID reused with different content","value":{"message":"This updateId was already used with different content.","error":"Conflict","statusCode":409}},"alreadyResolved":{"summary":"An update to a resolved case","value":{"message":"The case is already resolved; new updates cannot reopen it.","error":"Conflict","statusCode":409}},"environmentRetired":{"summary":"A key of a retired workspace","value":{"code":"ENVIRONMENT_RETIRED","message":"This API key belongs to an earlier copy of your organization's workspace, which was retired. Create a new key in your workspace (Integrations, API keys) and use it instead."}}}}}},"429":{"description":"`RATE_LIMITED`: this API key has sent more requests than it may on all the routes it can call together (the clinical-case routes, the conversation gateway and Patient messaging): 600 a minute and 20,000 an hour. Nothing is read, written or audited by a refused call. Honor `Retry-After` (seconds), then retry with the same identifiers.","headers":{"Retry-After":{"description":"Seconds to wait before the key may call again.","schema":{"type":"integer","minimum":1,"maximum":3600}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"code":"RATE_LIMITED","message":"This API key is sending requests faster than allowed (600 a minute). Wait for Retry-After, then retry with the same requestId."}}}}}}},"/v1/clinical-cases/{caseId}/updates":{"post":{"tags":["Clinical cases"],"operationId":"updateClinicalCase","summary":"Report provider-workflow progress","description":"Needs a key with the `care_handoff` scope. The first update must be `processed` at sequence 1, and only the first can be. Later updates may report scheduling, clinician response, patient contact, or final resolution, each at the next sequence (`nextSequence` from the progress endpoint). `scheduled` needs `scheduledFor` (a date and time with a time zone) and `visitUrl` (the link the patient joins the visit with: required, `https` only, a real website name, no username or password, at most 2000 characters; a missing or invalid link is `400` with a `code`), and no other status takes either. A case has one appointment, its latest `scheduled` update, which stays after later updates until you send `appointment_cancelled` (no time, no link; `409 NO_APPOINTMENT_TO_CANCEL` when there is none) or the case is resolved; another `scheduled` update, with its link again, moves it. The patient sees the time in their own time zone and a Join visit button in the widget (or your portal reads it from the conversation's `appointment`) from booking until an hour after the start, and the link is never in an email. A booking also queues email reminders to the patient a day and an hour before (one whose time has already passed is skipped; moving the appointment replaces them, cancelling it or resolving the case stops them). `resolved` needs `resolutionOutcome` and a `resolutionNote` of 10 to 2000 characters and no other status takes them. Resolution is final: once the case is resolved, whether by you or by a team member in NezerCare, further updates are `409`. Use the same updateId and identical body when retrying: the answer is `200` with `duplicate: true`, even after later updates. Every status except `processed` also queues a short care-update email to the patient (\"An appointment was scheduled\", \"Your appointment was cancelled\", \"Your care team has responded\", \"Your care team recorded contact with you\", \"Your care request was closed\"), with no medical detail (not sent for a case of the clinic's own patient portal when the clinic chose \"Your portal only\" for who tells the patient). Updates and messages that arrive close together are one email: the first waits about 30 seconds for the rest, and the email says the most important thing in that burst (a closed case, then an appointment with its time, then a reply, then a recorded contact; between two appointment updates, the later), so a message and a `clinician_responded` update sent together are one \"Your care team has responded\", never two. Appointment reminders are separate emails. An update is recorded and audited but sends no webhook back to you, and a `resolved` update doesn't send `clinical_case.resolved`.","parameters":[{"name":"caseId","in":"path","required":true,"description":"The canonical UUID from the clinical_case.opened webhook. This is not the patient-facing NC-XXXXXXXX reference.","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CaseUpdate"},"examples":{"processed":{"summary":"Provider workflow created","value":{"updateId":"d574b886-f658-43dc-a62a-6c66ef74682d","sequence":1,"status":"processed","externalReference":"provider-conversation-001"}},"scheduled":{"summary":"Appointment scheduled","value":{"updateId":"8bb876eb-c77e-4686-b8f0-e4f76333670a","sequence":2,"status":"scheduled","externalReference":"appointment-456","scheduledFor":"2026-09-08T14:30:00-04:00","visitUrl":"https://visit.example-clinic.com/rooms/456"}},"appointmentCancelled":{"summary":"Appointment cancelled","value":{"updateId":"3d2c0f0a-6b9e-4b7e-9d8c-5f3a2b1c0e77","sequence":3,"status":"appointment_cancelled","externalReference":"appointment-456"}},"resolved":{"summary":"Case resolved","value":{"updateId":"947ea6c9-cdb3-48d7-874b-bfcd59b54e99","sequence":3,"status":"resolved","externalReference":"provider-conversation-001","resolutionOutcome":"provider_follow_up","resolutionNote":"Clinician reviewed the concern and provided follow-up guidance."}}}}}},"responses":{"200":{"description":"Progress recorded or an identical retry recognized.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CaseUpdateResult"}}}},"400":{"description":"The request is malformed or breaks the operation's contract: a field of the wrong type or outside its limits, a field the operation doesn't take (unknown fields are refused, not ignored), or an ID that isn't a UUID. `message` is a sentence, or a list of sentences, one for each field that failed. A `scheduled` update's `visitUrl` is checked on its own and answered with a `code` and one sentence that says what to fix: `VISIT_URL_REQUIRED` (missing or empty), `VISIT_URL_INVALID` (not a web address, not text, too long, or spaces or hidden characters in it) or `VISIT_URL_NOT_ALLOWED` (not `https`, a username or password in it, an IP address, a private name such as `localhost` or `.internal`, or a `visitUrl` on an update that isn't `scheduled`). Nothing is recorded for a refused update.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"validation":{"summary":"A field outside its limits","value":{"message":["resolutionNote must be longer than or equal to 10 characters"],"error":"Bad Request","statusCode":400}},"visitUrlRequired":{"summary":"A booking without a visit link","value":{"code":"VISIT_URL_REQUIRED","message":"A visit link is required to book an appointment. Add the link the patient uses to join the visit.","error":"Bad Request","statusCode":400}},"visitUrlNotAllowed":{"summary":"A link that isn't https","value":{"code":"VISIT_URL_NOT_ALLOWED","message":"The visit link must start with https://.","error":"Bad Request","statusCode":400}}}}}},"401":{"description":"`MISSING_API_CREDENTIAL`: no bearer key was sent. `INVALID_API_CREDENTIAL`: the key is invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing":{"summary":"No key sent","value":{"code":"MISSING_API_CREDENTIAL","message":"A bearer API credential is required."}},"invalid":{"summary":"Invalid, expired or revoked key","value":{"code":"INVALID_API_CREDENTIAL","message":"API credential is invalid."}}}}}},"403":{"description":"`BAA_REQUIRED`: the organization hasn't signed its BAA, so patient features (and API keys) are off. An owner or administrator signs it in Settings; it takes effect within about half a minute. `INSUFFICIENT_SCOPE`: the key wasn't made for this route (see the scope in the operation's description); make a new key with the scope, as a key never gains one later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"baaRequired":{"summary":"BAA not signed","value":{"code":"BAA_REQUIRED","message":"Sign your BAA to turn on patient features. An owner or administrator can sign it in Settings."}},"insufficientScope":{"summary":"The key lacks the scope","value":{"code":"INSUFFICIENT_SCOPE","message":"This API key doesn't have the care_handoff scope. Create a key with it in Integrations, API keys."}}}}}},"404":{"description":"No case with this ID in the key's organization. Another organization's case and one that never existed look the same.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"message":"Case not found.","error":"Not Found","statusCode":404}}}},"409":{"description":"A conflict; the body says which. A `updateId` or `messageId` reused with different content. An update out of sequence (the body carries `nextSequence`), a first update that isn't `processed`, or an update to a case that is already resolved. An `appointment_cancelled` update when the case has no appointment (code `NO_APPOINTMENT_TO_CANCEL`). Or (code `ENVIRONMENT_RETIRED`) the API key belongs to an earlier copy of the organization's workspace that was retired in October 2026: every request with it is refused; create a new key in the workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"outOfSequence":{"summary":"An update out of sequence","value":{"message":"Update out of sequence.","nextSequence":2}},"idReused":{"summary":"An ID reused with different content","value":{"message":"This updateId was already used with different content.","error":"Conflict","statusCode":409}},"alreadyResolved":{"summary":"An update to a resolved case","value":{"message":"The case is already resolved; new updates cannot reopen it.","error":"Conflict","statusCode":409}},"noAppointment":{"summary":"A cancellation with no appointment to cancel","value":{"code":"NO_APPOINTMENT_TO_CANCEL","message":"There is no appointment to cancel.","error":"Conflict","statusCode":409}},"environmentRetired":{"summary":"A key of a retired workspace","value":{"code":"ENVIRONMENT_RETIRED","message":"This API key belongs to an earlier copy of your organization's workspace, which was retired. Create a new key in your workspace (Integrations, API keys) and use it instead."}}}}}},"429":{"description":"`RATE_LIMITED`: this API key has sent more requests than it may on all the routes it can call together (the clinical-case routes, the conversation gateway and Patient messaging): 600 a minute and 20,000 an hour. Nothing is read, written or audited by a refused call. Honor `Retry-After` (seconds), then retry with the same identifiers.","headers":{"Retry-After":{"description":"Seconds to wait before the key may call again.","schema":{"type":"integer","minimum":1,"maximum":3600}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"code":"RATE_LIMITED","message":"This API key is sending requests faster than allowed (600 a minute). Wait for Retry-After, then retry with the same requestId."}}}}}}},"/v1/clinical-cases/{caseId}/messages":{"post":{"tags":["Clinical cases"],"operationId":"sendClinicalCaseMessage","summary":"Send a message to the patient","description":"Needs a key with the `care_handoff` scope. The encrypted message appears in the patient's secure case conversation. Do not put internal clinical notes in this patient-visible field. The patient receives a privacy-safe email without the message body, about 30 seconds later, one email for messages and updates that arrive together (not for a case of the clinic's own patient portal when the clinic chose \"Your portal only\" for who tells the patient). A message to a resolved case is accepted, but a portal conversation that has closed doesn't take it into its feed. A retry with the same `messageId` and the same words is `200` with `duplicate: true`; the same `messageId` with other words is `409`.","parameters":[{"name":"caseId","in":"path","required":true,"description":"The canonical UUID from the clinical_case.opened webhook. This is not the patient-facing NC-XXXXXXXX reference.","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProviderMessage"},"example":{"messageId":"a321530a-f9fe-4435-8593-38eb75174854","message":"A clinician reviewed your concern. Have your symptoms changed today?","externalReference":"provider-message-456"}}}},"responses":{"200":{"description":"Message created or an identical retry recognized.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProviderMessageResult"}}}},"400":{"description":"The request is malformed or breaks the operation's contract: a field of the wrong type or outside its limits, a field the operation doesn't take (unknown fields are refused, not ignored), or an ID that isn't a UUID. `message` is a sentence, or a list of sentences, one for each field that failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"message":["resolutionNote must be longer than or equal to 10 characters"],"error":"Bad Request","statusCode":400}}}},"401":{"description":"`MISSING_API_CREDENTIAL`: no bearer key was sent. `INVALID_API_CREDENTIAL`: the key is invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing":{"summary":"No key sent","value":{"code":"MISSING_API_CREDENTIAL","message":"A bearer API credential is required."}},"invalid":{"summary":"Invalid, expired or revoked key","value":{"code":"INVALID_API_CREDENTIAL","message":"API credential is invalid."}}}}}},"403":{"description":"`BAA_REQUIRED`: the organization hasn't signed its BAA, so patient features (and API keys) are off. An owner or administrator signs it in Settings; it takes effect within about half a minute. `INSUFFICIENT_SCOPE`: the key wasn't made for this route (see the scope in the operation's description); make a new key with the scope, as a key never gains one later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"baaRequired":{"summary":"BAA not signed","value":{"code":"BAA_REQUIRED","message":"Sign your BAA to turn on patient features. An owner or administrator can sign it in Settings."}},"insufficientScope":{"summary":"The key lacks the scope","value":{"code":"INSUFFICIENT_SCOPE","message":"This API key doesn't have the care_handoff scope. Create a key with it in Integrations, API keys."}}}}}},"404":{"description":"No case with this ID in the key's organization. Another organization's case and one that never existed look the same.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"message":"Case not found.","error":"Not Found","statusCode":404}}}},"409":{"description":"A conflict; the body says which. A `updateId` or `messageId` reused with different content. An update out of sequence (the body carries `nextSequence`), a first update that isn't `processed`, or an update to a case that is already resolved. Or (code `ENVIRONMENT_RETIRED`) the API key belongs to an earlier copy of the organization's workspace that was retired in October 2026: every request with it is refused; create a new key in the workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"outOfSequence":{"summary":"An update out of sequence","value":{"message":"Update out of sequence.","nextSequence":2}},"idReused":{"summary":"An ID reused with different content","value":{"message":"This updateId was already used with different content.","error":"Conflict","statusCode":409}},"alreadyResolved":{"summary":"An update to a resolved case","value":{"message":"The case is already resolved; new updates cannot reopen it.","error":"Conflict","statusCode":409}},"environmentRetired":{"summary":"A key of a retired workspace","value":{"code":"ENVIRONMENT_RETIRED","message":"This API key belongs to an earlier copy of your organization's workspace, which was retired. Create a new key in your workspace (Integrations, API keys) and use it instead."}}}}}},"429":{"description":"`RATE_LIMITED`: this API key has sent more requests than it may on all the routes it can call together (the clinical-case routes, the conversation gateway and Patient messaging): 600 a minute and 20,000 an hour. Nothing is read, written or audited by a refused call. Honor `Retry-After` (seconds), then retry with the same identifiers.","headers":{"Retry-After":{"description":"Seconds to wait before the key may call again.","schema":{"type":"integer","minimum":1,"maximum":3600}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"code":"RATE_LIMITED","message":"This API key is sending requests faster than allowed (600 a minute). Wait for Retry-After, then retry with the same requestId."}}}}}}},"/v1/conversations/{conversationId}/messages":{"get":{"tags":["Conversations"],"operationId":"listConversationMessages","summary":"Read an ordered conversation","description":"Needs a key with the `conversation_gateway` scope. The thread as the patient sees it, in order, for a conversation of any category. Staff-only internal notes (a hand-off summary, a note the team wrote) are left out unless `includeInternal=true`, which also needs the `conversation_internal_notes` scope (`403 INSUFFICIENT_SCOPE` without it; only an owner or administrator can give a key that scope, and no key made before it existed has it); then every message in the answer has a `visibility`, `patient` or `internal` (it is on each message either way). Any `includeInternal` value but `true` reads as `false`. Internal notes are for your own staff tools: never show them to a patient. The answer is a plain JSON array of up to 250 messages after `afterSequence`; when 250 come back, ask again with the last `sequence`. Each read that returns a message is recorded in the workspace's audit log with the key and the conversation, never the messages. This is not what a patient portal reads: a portal uses Patient messaging.","parameters":[{"name":"conversationId","in":"path","required":true,"description":"The conversation's ID in NezerCare. This API has no call that lists conversations or finds one, and no webhook announces them. It isn't a clinical case's `caseId` and isn't the `conversationId` of Patient messaging, which names a portal conversation of its own.","schema":{"type":"string","format":"uuid"}},{"name":"afterSequence","in":"query","description":"Only messages after this sequence number; 0 reads from the start.","schema":{"type":"integer","minimum":0,"default":0}},{"name":"includeInternal","in":"query","description":"`true` adds the team's internal notes, marked `visibility: \"internal\"`; needs the `conversation_internal_notes` scope. Leave it out for anything a patient sees. Any other value reads as `false`.","schema":{"type":"boolean","default":false}}],"responses":{"200":{"description":"Messages ordered by ascending sequence: patient-visible only, or every message with `includeInternal=true`. A plain JSON array, empty when there is nothing after `afterSequence`.","content":{"application/json":{"schema":{"type":"array","maxItems":250,"items":{"$ref":"#/components/schemas/ConversationMessage"}},"example":[{"id":"620e855b-cb3d-4823-9260-1b8935693e38","organizationId":"6b1f2c3d-4e5f-4a6b-8c7d-0e1f2a3b4c5d","environmentId":"1d2c3b4a-5e6f-4a7b-8c9d-0e1f2a3b4c5d","conversationId":"ec768b8c-acad-49df-8c8e-438494dd320a","sequence":1,"senderType":"patient","senderId":"2c3d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f","direction":"inbound","requestHash":"b8ec3ec479f2bc3e52653b57bd56c35955d592162d3f6e61e33eeb04c78505e1","externalMessageId":null,"createdAt":"2026-10-21T04:28:23.042Z","visibility":"patient","attachments":[],"message":"I was charged twice for my last order"}]}}},"400":{"description":"The request is malformed or breaks the operation's contract: a field of the wrong type or outside its limits, a field the operation doesn't take (unknown fields are refused, not ignored), or an ID that isn't a UUID. `message` is a sentence, or a list of sentences, one for each field that failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"message":["message must be shorter than or equal to 10000 characters"],"error":"Bad Request","statusCode":400}}}},"401":{"description":"`MISSING_API_CREDENTIAL`: no bearer key was sent. `INVALID_API_CREDENTIAL`: the key is invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing":{"summary":"No key sent","value":{"code":"MISSING_API_CREDENTIAL","message":"A bearer API credential is required."}},"invalid":{"summary":"Invalid, expired or revoked key","value":{"code":"INVALID_API_CREDENTIAL","message":"API credential is invalid."}}}}}},"403":{"description":"`BAA_REQUIRED`: the organization hasn't signed its BAA, so patient features (and API keys) are off. An owner or administrator signs it in Settings; it takes effect within about half a minute. `INSUFFICIENT_SCOPE`: the key wasn't made for this route (see the scope in the operation's description); make a new key with the scope, as a key never gains one later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"baaRequired":{"summary":"BAA not signed","value":{"code":"BAA_REQUIRED","message":"Sign your BAA to turn on patient features. An owner or administrator can sign it in Settings."}},"insufficientScope":{"summary":"The key lacks the scope","value":{"code":"INSUFFICIENT_SCOPE","message":"This API key doesn't have the conversation_gateway scope. Create a key with it in Integrations, API keys."}}}}}},"404":{"description":"No conversation with this ID in the key's organization, or (on the delivery receipt) no message of it that NezerCare queued for your system. Another organization's looks the same as one that never existed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"message":"Conversation not found.","error":"Not Found","statusCode":404}}}},"409":{"description":"A conflict; the body says which. A `requestId` reused with different content, or a message to a closed conversation. Or (code `ENVIRONMENT_RETIRED`) the API key belongs to an earlier copy of the organization's workspace that was retired in October 2026: every request with it is refused; create a new key in the workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"idReused":{"summary":"An ID reused with different content","value":{"message":"This requestId was already used with different content.","error":"Conflict","statusCode":409}},"closed":{"summary":"A message to a closed conversation","value":{"message":"Conversation is closed.","error":"Conflict","statusCode":409}},"environmentRetired":{"summary":"A key of a retired workspace","value":{"code":"ENVIRONMENT_RETIRED","message":"This API key belongs to an earlier copy of your organization's workspace, which was retired. Create a new key in your workspace (Integrations, API keys) and use it instead."}}}}}},"429":{"description":"`RATE_LIMITED`: this API key has sent more requests than it may on all the routes it can call together (the clinical-case routes, the conversation gateway and Patient messaging): 600 a minute and 20,000 an hour. Nothing is read, written or audited by a refused call. Honor `Retry-After` (seconds), then retry with the same identifiers.","headers":{"Retry-After":{"description":"Seconds to wait before the key may call again.","schema":{"type":"integer","minimum":1,"maximum":3600}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"code":"RATE_LIMITED","message":"This API key is sending requests faster than allowed (600 a minute). Wait for Retry-After, then retry with the same requestId."}}}}}},"post":{"tags":["Conversations"],"operationId":"sendConversationMessage","summary":"Send a message from your system","description":"Needs a key with the `conversation_gateway` scope. Adds a message from your system to the conversation: stored as `senderType: external`, `direction: inbound` and patient-visible. NezerCare does not route it, answer it or run the emergency check on it, and it doesn't email the patient, so this is not how a patient's words reach NezerCare (a patient portal uses Patient messaging for that). In a conversation that a patient portal also shows, the message appears in the portal's feed as a message from the care team. `attachments` are records of files you hold (a name, a type and a SHA-256); this API stores no file and has no upload or download call. `409` when the conversation is closed. A retry with the same `requestId` and the same words is `201` with `duplicate: true`; the same `requestId` with other words is `409`.","parameters":[{"name":"conversationId","in":"path","required":true,"description":"The conversation's ID in NezerCare. This API has no call that lists conversations or finds one, and no webhook announces them. It isn't a clinical case's `caseId` and isn't the `conversationId` of Patient messaging, which names a portal conversation of its own.","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversationMessageInput"}}}},"responses":{"201":{"description":"Message created, or an identical retry recognized (`duplicate: true`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversationMessageResult"},"example":{"conversationId":"ec768b8c-acad-49df-8c8e-438494dd320a","messageId":"55555555-2222-4333-8444-555555555555","sequence":4,"duplicate":false,"createdAt":"2026-10-21T04:29:06.691Z"}}}},"400":{"description":"The request is malformed or breaks the operation's contract: a field of the wrong type or outside its limits, a field the operation doesn't take (unknown fields are refused, not ignored), or an ID that isn't a UUID. `message` is a sentence, or a list of sentences, one for each field that failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"message":["message must be shorter than or equal to 10000 characters"],"error":"Bad Request","statusCode":400}}}},"401":{"description":"`MISSING_API_CREDENTIAL`: no bearer key was sent. `INVALID_API_CREDENTIAL`: the key is invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing":{"summary":"No key sent","value":{"code":"MISSING_API_CREDENTIAL","message":"A bearer API credential is required."}},"invalid":{"summary":"Invalid, expired or revoked key","value":{"code":"INVALID_API_CREDENTIAL","message":"API credential is invalid."}}}}}},"403":{"description":"`BAA_REQUIRED`: the organization hasn't signed its BAA, so patient features (and API keys) are off. An owner or administrator signs it in Settings; it takes effect within about half a minute. `INSUFFICIENT_SCOPE`: the key wasn't made for this route (see the scope in the operation's description); make a new key with the scope, as a key never gains one later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"baaRequired":{"summary":"BAA not signed","value":{"code":"BAA_REQUIRED","message":"Sign your BAA to turn on patient features. An owner or administrator can sign it in Settings."}},"insufficientScope":{"summary":"The key lacks the scope","value":{"code":"INSUFFICIENT_SCOPE","message":"This API key doesn't have the conversation_gateway scope. Create a key with it in Integrations, API keys."}}}}}},"404":{"description":"No conversation with this ID in the key's organization, or (on the delivery receipt) no message of it that NezerCare queued for your system. Another organization's looks the same as one that never existed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"message":"Conversation not found.","error":"Not Found","statusCode":404}}}},"409":{"description":"A conflict; the body says which. A `requestId` reused with different content, or a message to a closed conversation. Or (code `ENVIRONMENT_RETIRED`) the API key belongs to an earlier copy of the organization's workspace that was retired in October 2026: every request with it is refused; create a new key in the workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"idReused":{"summary":"An ID reused with different content","value":{"message":"This requestId was already used with different content.","error":"Conflict","statusCode":409}},"closed":{"summary":"A message to a closed conversation","value":{"message":"Conversation is closed.","error":"Conflict","statusCode":409}},"environmentRetired":{"summary":"A key of a retired workspace","value":{"code":"ENVIRONMENT_RETIRED","message":"This API key belongs to an earlier copy of your organization's workspace, which was retired. Create a new key in your workspace (Integrations, API keys) and use it instead."}}}}}},"429":{"description":"`RATE_LIMITED`: this API key has sent more requests than it may on all the routes it can call together (the clinical-case routes, the conversation gateway and Patient messaging): 600 a minute and 20,000 an hour. Nothing is read, written or audited by a refused call. Honor `Retry-After` (seconds), then retry with the same identifiers.","headers":{"Retry-After":{"description":"Seconds to wait before the key may call again.","schema":{"type":"integer","minimum":1,"maximum":3600}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"code":"RATE_LIMITED","message":"This API key is sending requests faster than allowed (600 a minute). Wait for Retry-After, then retry with the same requestId."}}}}}}},"/v1/conversations/{conversationId}/messages/{messageId}/delivery":{"post":{"tags":["Conversations"],"operationId":"updateConversationMessageDelivery","summary":"Report external delivery state","description":"Needs a key with the `conversation_gateway` scope. A receipt is only taken for a message NezerCare queued for your system to pass on to the patient: an outbound, patient-visible message of your workspace. For a patient's own message, an internal note, a message of another conversation or another workspace, or an ID that doesn't exist, the answer is `404` and nothing is recorded.","parameters":[{"name":"conversationId","in":"path","required":true,"description":"The conversation's ID in NezerCare. This API has no call that lists conversations or finds one, and no webhook announces them. It isn't a clinical case's `caseId` and isn't the `conversationId` of Patient messaging, which names a portal conversation of its own.","schema":{"type":"string","format":"uuid"}},{"name":"messageId","in":"path","required":true,"description":"The ID of the message the receipt is for (its `id` in the thread).","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversationDeliveryUpdate"}}}},"responses":{"201":{"description":"Delivery state recorded. A repeat of the same status for the same `externalMessageId` is answered the same way (`201`, with no `duplicate` flag) and is not recorded again. A `failed` receipt opens a high-priority work item for the care team.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversationDeliveryResult"},"example":{"conversationId":"ec768b8c-acad-49df-8c8e-438494dd320a","messageId":"b7ad7856-5ab6-4fea-b978-e174ec033350","status":"delivered","updatedAt":"2026-10-21T04:30:22.621Z"}}}},"400":{"description":"The request is malformed or breaks the operation's contract: a field of the wrong type or outside its limits, a field the operation doesn't take (unknown fields are refused, not ignored), or an ID that isn't a UUID. `message` is a sentence, or a list of sentences, one for each field that failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"message":["message must be shorter than or equal to 10000 characters"],"error":"Bad Request","statusCode":400}}}},"401":{"description":"`MISSING_API_CREDENTIAL`: no bearer key was sent. `INVALID_API_CREDENTIAL`: the key is invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing":{"summary":"No key sent","value":{"code":"MISSING_API_CREDENTIAL","message":"A bearer API credential is required."}},"invalid":{"summary":"Invalid, expired or revoked key","value":{"code":"INVALID_API_CREDENTIAL","message":"API credential is invalid."}}}}}},"403":{"description":"`BAA_REQUIRED`: the organization hasn't signed its BAA, so patient features (and API keys) are off. An owner or administrator signs it in Settings; it takes effect within about half a minute. `INSUFFICIENT_SCOPE`: the key wasn't made for this route (see the scope in the operation's description); make a new key with the scope, as a key never gains one later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"baaRequired":{"summary":"BAA not signed","value":{"code":"BAA_REQUIRED","message":"Sign your BAA to turn on patient features. An owner or administrator can sign it in Settings."}},"insufficientScope":{"summary":"The key lacks the scope","value":{"code":"INSUFFICIENT_SCOPE","message":"This API key doesn't have the conversation_gateway scope. Create a key with it in Integrations, API keys."}}}}}},"404":{"description":"No conversation with this ID in the key's organization, or (on the delivery receipt) no message of it that NezerCare queued for your system. Another organization's looks the same as one that never existed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"message":"Conversation not found.","error":"Not Found","statusCode":404}}}},"409":{"description":"A conflict; the body says which. A `requestId` reused with different content, or a message to a closed conversation. Or (code `ENVIRONMENT_RETIRED`) the API key belongs to an earlier copy of the organization's workspace that was retired in October 2026: every request with it is refused; create a new key in the workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"idReused":{"summary":"An ID reused with different content","value":{"message":"This requestId was already used with different content.","error":"Conflict","statusCode":409}},"closed":{"summary":"A message to a closed conversation","value":{"message":"Conversation is closed.","error":"Conflict","statusCode":409}},"environmentRetired":{"summary":"A key of a retired workspace","value":{"code":"ENVIRONMENT_RETIRED","message":"This API key belongs to an earlier copy of your organization's workspace, which was retired. Create a new key in your workspace (Integrations, API keys) and use it instead."}}}}}},"429":{"description":"`RATE_LIMITED`: this API key has sent more requests than it may on all the routes it can call together (the clinical-case routes, the conversation gateway and Patient messaging): 600 a minute and 20,000 an hour. Nothing is read, written or audited by a refused call. Honor `Retry-After` (seconds), then retry with the same identifiers.","headers":{"Retry-After":{"description":"Seconds to wait before the key may call again.","schema":{"type":"integer","minimum":1,"maximum":3600}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"code":"RATE_LIMITED","message":"This API key is sending requests faster than allowed (600 a minute). Wait for Retry-After, then retry with the same requestId."}}}}}}}},"webhooks":{"orderLookupRequested":{"post":{"tags":["Webhooks"],"operationId":"orderLookupRequested","summary":"order_lookup.requested","description":"Sent by an active \"Order status and tracking\" workflow when a signed-in patient asks where their order is (English or Spanish), to your connection's address + the step's path (POST /orders/lookup in the template). Never sent for an anonymous visitor, a health question or an emergency, and never contains what the patient typed. One attempt; NezerCare waits up to 5 seconds (less if the connection says so). Answer 200 with an `orders` array, empty when there are none. Anything else (a status that isn't 2xx, a redirect, which isn't followed, no answer in time, or an answer that breaks the contract) makes the workflow say it couldn't check and offer the team; nothing is guessed.\n\nVerify `x-nezer-signature` with your workspace's **widget signing secret**: the lowercase hex HMAC-SHA256 of `<x-nezer-timestamp>.<METHOD> <path and query>\\n<raw body>`, compared after `v1=` in constant time. Reject a timestamp more than five minutes from now.","parameters":[{"name":"x-nezer-timestamp","in":"header","required":true,"schema":{"type":"string","pattern":"^[0-9]+$"},"description":"Unix seconds."},{"name":"x-nezer-signature","in":"header","required":true,"schema":{"type":"string","pattern":"^v1=[a-f0-9]{64}$"},"description":"v1=<hex HMAC-SHA256 of timestamp + '.' + METHOD + ' ' + path and query + '\\n' + raw body>, keyed with the widget signing secret."},{"name":"x-nezer-test","in":"header","required":false,"schema":{"type":"string","enum":["true"]},"description":"Present on calls for a made-up test patient while NezerCare sets your workspace up (its test run). Don't change real orders or accounts for such a call; answer as you would in a test or sandbox."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderLookupRequest"}}}},"responses":{"200":{"description":"The patient's orders (latest first, or with placedAt on each). At most three are shown.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderLookupResponse"},"examples":{"orders":{"summary":"Orders found","value":{"orders":[{"id":"TEST-1003","status":"shipped","statusLabel":"On its way","carrier":"UPS","trackingUrl":"https://www.ups.com/track?tracknum=1Z0000000000000000","estimatedDelivery":"2026-10-02","placedAt":"2026-09-25T15:04:00Z","items":[{"name":"Test Product A","quantity":1}]},{"id":"TEST-1001","status":"delivered","carrier":"USPS","placedAt":"2026-08-28T12:00:00Z"}]}},"none":{"summary":"No orders for this patient","value":{"orders":[]}}}}}}}}},"patientSearchRequested":{"post":{"tags":["Webhooks"],"operationId":"patientSearchRequested","summary":"patient_search.requested","description":"Sent when a teammate asks @Nezer in your Slack channel to message a group of patients described in words (\"everyone whose UPS order shipped from Dallas last week\"), and to test a search from the staff app, to your connection's address + the search's path. It carries only the filters your search declares, as checked by NezerCare: choice values you set up, dates (YYYY-MM-DD), date ranges (both days included, at most 93 days, within 366 days back and 92 days ahead of today in the clinic's time zone) and codes. Never patient data, and never anything a teammate typed. One attempt per page; NezerCare waits up to 5 seconds, reads at most 4 pages, and stops once it has more than 50 different patients' IDs (one message's limit). Answer 200 with the patients' IDs. Anything else (a status that isn't 2xx, a redirect, which isn't followed, no answer in time, or an answer that breaks the contract) makes @Nezer say it couldn't search; nothing is sent to anyone.\n\nEvery call is signed: a search can't be tested or turned on until the workspace has a widget signing secret. Verify `x-nezer-signature` with that **widget signing secret**, exactly as for a workflow call: the lowercase hex HMAC-SHA256 of `<x-nezer-timestamp>.<METHOD> <path and query>\\n<raw body>`, compared after `v1=` in constant time. Reject a timestamp more than five minutes from now.","parameters":[{"name":"x-nezer-timestamp","in":"header","required":true,"schema":{"type":"string","pattern":"^[0-9]+$"},"description":"Unix seconds."},{"name":"x-nezer-signature","in":"header","required":true,"schema":{"type":"string","pattern":"^v1=[a-f0-9]{64}$"},"description":"v1=<hex HMAC-SHA256 of timestamp + '.' + METHOD + ' ' + path and query + '\\n' + raw body>, keyed with the widget signing secret."},{"name":"x-nezer-test","in":"header","required":false,"schema":{"type":"string","enum":["true"]},"description":"Present on a test from the staff app (and NezerCare setup's). Answer as you would for real: the test shows the counts and how many of your IDs are patients in Nezer."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatientSearchRequest"}}}},"responses":{"200":{"description":"The patients found: their IDs only, a total, and a cursor for the next page.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatientSearchResponse"},"examples":{"found":{"summary":"Patients found","value":{"patients":[{"id":"TEST-1001"},{"id":"TEST-1002"}],"total":2,"nextCursor":null}},"paged":{"summary":"More on the next page","value":{"patients":[{"id":"TEST-1001"}],"total":63,"nextCursor":"page-2"}},"none":{"summary":"No one found","value":{"patients":[],"total":0}}}}}}}}},"conversationMessageCreated":{"post":{"tags":["Webhooks"],"operationId":"conversationMessageCreatedWebhook","summary":"conversation.message_created","description":"One message was added to a portal conversation: the patient's own, NezerCare's reply (an answer, a hand-off, a notice, an emergency notice) or the care team's.\n\nSent to the endpoint you subscribed in Integrations, Notifications, signed and retried like every other event (return 2xx after durable receipt; verify the raw-body signature and deduplicate by `x-nezer-event-id` and by the message's `id`). The body holds patient messages: keep it out of ordinary application logs. Until the organization has signed its BAA these wait, and go out once it signs.\n\n**Webhooks are for speed; the feed is the truth.** Delivery is at least once, in parallel, with no promised order, and a delivery gives up after 12 attempts. Apply messages by `sequence`, not by arrival. When a message's `sequence` is more than one above the last you have, or when a conversation opens, read `GET /v1/patients/{patientId}/conversations/{conversationId}/messages?afterSequence=<the last you have>` and apply what it returns.\n\nInternal notes, resolution notes and everything staff-only are never in an event. A patient's own messages and NezerCare's replies to them are sent too (tagged with `causedByRequestId`), so a second device or tab sees them: drop the ones you already have.\n\n**An `emergency` message must be shown at once**, in full, in these words, like the one in the response of the call that caused it. The webhook is never the only way you hear of it: the response to the patient's call carries it first.","parameters":[{"name":"x-nezer-event-id","in":"header","required":true,"description":"The event's ID, the same as the body's `id`. A retry reuses it: deduplicate on it.","schema":{"type":"string","format":"uuid"}},{"name":"x-nezer-event-type","in":"header","required":true,"description":"The event's name.","schema":{"type":"string"}},{"name":"x-nezer-timestamp","in":"header","required":true,"description":"When this attempt was signed, in seconds since the epoch. A retry is signed afresh.","schema":{"type":"string","pattern":"^[0-9]+$"}},{"name":"x-nezer-signature","in":"header","required":true,"description":"`v1=` and the lowercase hex HMAC-SHA256 of `<x-nezer-timestamp>.<raw request body>`, keyed with the endpoint's signing secret.","schema":{"type":"string","pattern":"^v1=[a-f0-9]{64}$"}},{"name":"idempotency-key","in":"header","required":true,"description":"The same value as `x-nezer-event-id`.","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PortalMessageCreatedEvent"},"examples":{"careTeamReply":{"summary":"The care team replied","value":{"id":"5f0c1d7e-3a5b-4c6d-9e8f-0a1b2c3d4e5f","type":"conversation.message_created","createdAt":"2026-10-18T16:21:45.000Z","data":{"conversationId":"4a1c8e90-2b7d-4f36-9c05-7d3e1a6b8f12","externalConversationId":"portal-thread-991","patientId":"2c3d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f","externalPatientId":"pt_48213","sequence":3,"message":{"id":"e5f6a7b8-c9d0-4e1f-8a3b-4c5d6e7f8091","sequence":3,"kind":"text","from":{"kind":"care_team","label":"Care team"},"priority":"normal","language":"en","text":"Please keep the spot clean and dry. A nurse will call you today.","createdAt":"2026-10-18T16:21:44.000Z"},"conversation":{"status":"open","careStatus":{"code":"replied","label":"New reply from your care team"},"showCall911":false,"version":7}}}},"emergency":{"summary":"An emergency notice","value":{"id":"5f0c1d7e-3a5b-4c6d-9e8f-0a1b2c3d4e5f","type":"conversation.message_created","createdAt":"2026-10-18T16:21:45.000Z","data":{"conversationId":"4a1c8e90-2b7d-4f36-9c05-7d3e1a6b8f12","externalConversationId":"portal-thread-991","patientId":"2c3d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f","externalPatientId":"pt_48213","sequence":2,"message":{"id":"d4e5f6a7-b8c9-4d0e-9f2a-3b4c5d6e7f80","sequence":2,"kind":"emergency","from":{"kind":"nezer","label":"NezerCare"},"priority":"emergency","language":"en","text":"Call 911 now. What you described can need emergency care. Do not wait for your care team to reply.","emergency":{"lines":[{"label":"Call 911","tel":"tel:911"}],"sentToCareTeam":true},"causedByRequestId":"9d1f7a52-3c6e-4b85-8f0a-5b2c1d7e9a30","createdAt":"2026-10-18T15:09:30.000Z"},"conversation":{"status":"open","careStatus":{"code":"received","label":"Received"},"showCall911":true,"version":7}}}},"closed":{"summary":"The conversation closed","value":{"id":"5f0c1d7e-3a5b-4c6d-9e8f-0a1b2c3d4e5f","type":"conversation.message_created","createdAt":"2026-10-18T16:21:45.000Z","data":{"conversationId":"4a1c8e90-2b7d-4f36-9c05-7d3e1a6b8f12","externalConversationId":"portal-thread-991","patientId":"2c3d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f","externalPatientId":"pt_48213","sequence":4,"message":{"id":"f6a7b8c9-d0e1-4f2a-9b4c-5d6e7f809102","sequence":4,"kind":"closed","from":{"kind":"nezer","label":"NezerCare"},"priority":"normal","language":"en","text":"Closed","closed":{"reason":"closed"},"createdAt":"2026-10-18T17:02:00.000Z"},"conversation":{"status":"closed","careStatus":{"code":"closed","label":"Closed"},"showCall911":false,"version":9}}}}}}}},"responses":{"200":{"description":"Durably received. Any `2xx` status counts; anything else is retried."}}}},"conversationUpdated":{"post":{"tags":["Webhooks"],"operationId":"conversationUpdatedWebhook","summary":"conversation.updated","description":"A portal conversation's state changed with no message to carry the change: its `status`, `careStatus` (a teammate acknowledged the case: \"Your care team is on it\"), `appointment` (booked, moved or cancelled), `showCall911` or what it is `awaiting`. The body is the conversation as `GET /v1/patients/{patientId}/conversations/{conversationId}` returns it, except that `appointment` has only `scheduledFor`: a webhook never carries the visit link. A change that comes with a message arrives in that message's `conversation.message_created` instead, though one can still follow a message's event right away with the same `version` (applying it again changes nothing). Compare `conversation.version` with the one you hold and keep the higher.\n\nSent to the endpoint you subscribed in Integrations, Notifications, signed and retried like every other event (return 2xx after durable receipt; verify the raw-body signature and deduplicate by `x-nezer-event-id` and by the message's `id`). The body holds patient messages: keep it out of ordinary application logs. Until the organization has signed its BAA these wait, and go out once it signs.\n\n**Webhooks are for speed; the feed is the truth.** Delivery is at least once, in parallel, with no promised order, and a delivery gives up after 12 attempts. Apply messages by `sequence`, not by arrival. When a message's `sequence` is more than one above the last you have, or when a conversation opens, read `GET /v1/patients/{patientId}/conversations/{conversationId}/messages?afterSequence=<the last you have>` and apply what it returns.\n\nInternal notes, resolution notes and everything staff-only are never in an event. A patient's own messages and NezerCare's replies to them are sent too (tagged with `causedByRequestId`), so a second device or tab sees them: drop the ones you already have.","parameters":[{"name":"x-nezer-event-id","in":"header","required":true,"description":"The event's ID, the same as the body's `id`. A retry reuses it: deduplicate on it.","schema":{"type":"string","format":"uuid"}},{"name":"x-nezer-event-type","in":"header","required":true,"description":"The event's name.","schema":{"type":"string"}},{"name":"x-nezer-timestamp","in":"header","required":true,"description":"When this attempt was signed, in seconds since the epoch. A retry is signed afresh.","schema":{"type":"string","pattern":"^[0-9]+$"}},{"name":"x-nezer-signature","in":"header","required":true,"description":"`v1=` and the lowercase hex HMAC-SHA256 of `<x-nezer-timestamp>.<raw request body>`, keyed with the endpoint's signing secret.","schema":{"type":"string","pattern":"^v1=[a-f0-9]{64}$"}},{"name":"idempotency-key","in":"header","required":true,"description":"The same value as `x-nezer-event-id`.","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PortalConversationUpdatedEvent"},"example":{"id":"5f0c1d7e-3a5b-4c6d-9e8f-0a1b2c3d4e5f","type":"conversation.updated","createdAt":"2026-10-18T16:21:45.000Z","data":{"conversationId":"4a1c8e90-2b7d-4f36-9c05-7d3e1a6b8f12","externalConversationId":"portal-thread-991","patientId":"2c3d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f","externalPatientId":"pt_48213","conversation":{"id":"4a1c8e90-2b7d-4f36-9c05-7d3e1a6b8f12","patientId":"2c3d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f","externalConversationId":"portal-thread-991","channel":"portal_api","status":"open","careStatus":{"code":"in_progress","label":"Your care team is on it"},"appointment":null,"showCall911":false,"awaiting":{"type":"none"},"lastSequence":2,"version":4,"language":"en","safety":{"language":"en","emergencyLine":"If this is a medical emergency, call 911.","lines":[{"label":"Call 911","tel":"tel:911"}]},"createdAt":"2026-10-18T15:02:11.000Z","updatedAt":"2026-10-18T15:02:13.000Z"}}}}}},"responses":{"200":{"description":"Durably received. Any `2xx` status counts; anything else is retried."}}}},"clinicalCaseOpened":{"post":{"tags":["Webhooks"],"operationId":"clinicalCaseOpenedWebhook","summary":"clinical_case.opened","description":"Return 2xx after durable receipt. Verify the raw-body signature and deduplicate by x-nezer-event-id before creating or associating a provider workflow. The `handoff` paths are the API's own paths and start with `/api/v1/...`; on `https://api.nezercare.com` call them without the `/api` (`/v1/clinical-cases/{caseId}/updates`). No API key is sent in the webhook. `data.intake` holds the questions NezerCare asked the patient and their answers, so your system gets them with the case (the escalation to a Destination carries the same). One emergency is one event: a further emergency from the same patient within 15 minutes of an unresolved emergency case is added to that case and arrives as `clinical_case.patient_message_created`, not as a second `clinical_case.opened`.","parameters":[{"name":"x-nezer-event-id","in":"header","required":true,"description":"The event's ID, the same as the body's `id`. A retry of the delivery reuses it: deduplicate on it.","schema":{"type":"string","format":"uuid"}},{"name":"x-nezer-event-type","in":"header","required":true,"description":"The event's name, such as `clinical_case.opened`.","schema":{"type":"string"}},{"name":"x-nezer-timestamp","in":"header","required":true,"description":"When this attempt was signed, in seconds since the epoch. A retry is signed afresh.","schema":{"type":"string","pattern":"^[0-9]+$"}},{"name":"x-nezer-signature","in":"header","required":true,"description":"`v1=` and the lowercase hex HMAC-SHA256 of `<x-nezer-timestamp>.<raw request body>`, keyed with the endpoint's signing secret.","schema":{"type":"string","pattern":"^v1=[a-f0-9]{64}$"}},{"name":"idempotency-key","in":"header","required":true,"description":"The same value as `x-nezer-event-id`.","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClinicalCaseOpenedEvent"},"examples":{"healthConcern":{"summary":"A concern raised in the widget, triaged on your Health concerns","value":{"id":"5f0c1d7e-3a5b-4c6d-9e8f-0a1b2c3d4e5f","type":"clinical_case.opened","createdAt":"2026-10-11T14:05:00.000Z","data":{"caseId":"8a7b6c5d-4e3f-4a2b-9c1d-0e9f8a7b6c5d","checkInId":"1b2c3d4e-5f60-4a7b-8c9d-0e1f2a3b4c5d","patientId":"2c3d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f","priority":"urgent","status":"open","resolutionOutcome":null,"resolutionNote":null,"disposition":"clinical_escalation","source":"patient_concern","patientNotes":"Injection site reaction\n\nThere's a reddish spot where I injected and it's spreading.","intake":{"language":"en","questions":[{"kind":"safety","question":"Is the redness spreading quickly, or do you have a fever?","answer":"No","choice":"no"},{"kind":"follow_up","question":"When did you first notice it?","answer":"Two days ago, the evening after my Sunday dose."},{"kind":"follow_up","question":"Is it getting better, worse or staying the same?","answer":"Worse. It's about the size of a coin now and warm to the touch."}],"omittedQuestions":0},"symptomScores":{},"matchedRules":["ai_intake:injection_site_reaction"],"healthConcerns":{"version":3,"label":"Health concerns v3"},"submittedAt":"2026-10-11T14:05:00.000Z","handoff":{"caseId":"8a7b6c5d-4e3f-4a2b-9c1d-0e9f8a7b6c5d","updatesPath":"/api/v1/clinical-cases/8a7b6c5d-4e3f-4a2b-9c1d-0e9f8a7b6c5d/updates","progressPath":"/api/v1/clinical-cases/8a7b6c5d-4e3f-4a2b-9c1d-0e9f8a7b6c5d/progress","messagesPath":"/api/v1/clinical-cases/8a7b6c5d-4e3f-4a2b-9c1d-0e9f8a7b6c5d/messages","firstStatus":"processed","firstSequence":1,"transportReceiptIsClinicalAcceptance":false}}}}}}}},"responses":{"200":{"description":"Durably received. Any `2xx` status counts; anything else is retried."}}}},"caseEscalation":{"post":{"tags":["Webhooks"],"operationId":"caseEscalationToDestinationWebhook","summary":"Escalation to a Destination","description":"The other way a case reaches your system. When a concern type in your Health concerns has a Destination (\"Also send to\"), NezerCare also sends each case of that type, as it opens, to that Destination's address: a `POST` of the JSON below, authenticated with the credentials you set on the Destination (a bearer token, basic credentials or your API-key header; with \"API key in request body\" your key is instead an extra top-level `apiKey` field of the JSON, never a header). It is not signed: there is no `x-nezer-signature` or timestamp, and the Destination's own credentials are what it proves itself with. `caseId` and `handoff` are how your system reports back on the case, as for `clinical_case.opened`; `intake` is the same as there. Verify the credentials you set, deduplicate on the `Idempotency-Key` (the case's submission ID, `checkInId`: a retry sends the same payload with the same key) and return 2xx after durable receipt. A `2xx` is a receipt only, never a clinician's acceptance. A network error, a timeout, `408`, `429` or `5xx` is retried, up to eight attempts with a wait that doubles up to an hour; any other answer fails the send, and redirects are not followed. It can hold protected health information: keep it out of ordinary logs. A test patient's case is never sent.","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"The case's submission ID, the same as `checkInId`. A retry reuses it: deduplicate on it.","schema":{"type":"string","format":"uuid"}},{"name":"X-Nezer-Submission-Id","in":"header","required":true,"description":"NezerCare's ID for this send. The same on every attempt.","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CaseEscalation"},"examples":{"healthConcern":{"summary":"A concern raised in the widget, sent to your Destination","value":{"patientId":"2c3d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f","checkInId":"1b2c3d4e-5f60-4a7b-8c9d-0e1f2a3b4c5d","caseId":"8a7b6c5d-4e3f-4a2b-9c1d-0e9f8a7b6c5d","disposition":"clinical_escalation","matchedRules":["ai_intake:injection_site_reaction"],"notes":"Injection site reaction\n\nThere's a reddish spot where I injected and it's spreading.","intake":{"language":"en","questions":[{"kind":"safety","question":"Is the redness spreading quickly, or do you have a fever?","answer":"No","choice":"no"},{"kind":"follow_up","question":"When did you first notice it?","answer":"Two days ago, the evening after my Sunday dose."},{"kind":"follow_up","question":"Is it getting better, worse or staying the same?","answer":"Worse. It's about the size of a coin now and warm to the touch."}],"omittedQuestions":0},"priority":"urgent","handoff":{"caseId":"8a7b6c5d-4e3f-4a2b-9c1d-0e9f8a7b6c5d","updatesPath":"/api/v1/clinical-cases/8a7b6c5d-4e3f-4a2b-9c1d-0e9f8a7b6c5d/updates","progressPath":"/api/v1/clinical-cases/8a7b6c5d-4e3f-4a2b-9c1d-0e9f8a7b6c5d/progress","messagesPath":"/api/v1/clinical-cases/8a7b6c5d-4e3f-4a2b-9c1d-0e9f8a7b6c5d/messages","firstStatus":"processed","firstSequence":1,"transportReceiptIsClinicalAcceptance":false}}}}}}},"responses":{"200":{"description":"Durably received. Any `2xx` status counts; the retries above follow anything else."}}}},"patientMessageCreated":{"post":{"tags":["Webhooks"],"operationId":"clinicalCasePatientMessageCreatedWebhook","summary":"clinical_case.patient_message_created","description":"Contains patient-authored clinical content. Verify, deduplicate, and route it without placing the body in ordinary application logs. It is also how a patient's further emergency message arrives: within 15 minutes of an unresolved emergency case for the same patient it is added to that case, with this event on that case's `caseId` and no second `clinical_case.opened`. Do not treat it as a new emergency case.","parameters":[{"name":"x-nezer-event-id","in":"header","required":true,"description":"The event's ID, the same as the body's `id`. A retry of the delivery reuses it: deduplicate on it.","schema":{"type":"string","format":"uuid"}},{"name":"x-nezer-event-type","in":"header","required":true,"description":"The event's name, such as `clinical_case.opened`.","schema":{"type":"string"}},{"name":"x-nezer-timestamp","in":"header","required":true,"description":"When this attempt was signed, in seconds since the epoch. A retry is signed afresh.","schema":{"type":"string","pattern":"^[0-9]+$"}},{"name":"x-nezer-signature","in":"header","required":true,"description":"`v1=` and the lowercase hex HMAC-SHA256 of `<x-nezer-timestamp>.<raw request body>`, keyed with the endpoint's signing secret.","schema":{"type":"string","pattern":"^v1=[a-f0-9]{64}$"}},{"name":"idempotency-key","in":"header","required":true,"description":"The same value as `x-nezer-event-id`.","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatientMessageCreatedEvent"},"example":{"id":"ec6bf514-a01d-4406-8b76-6b1bb841617a","type":"clinical_case.patient_message_created","createdAt":"2026-10-21T04:34:54.527Z","data":{"caseId":"8a7b6c5d-4e3f-4a2b-9c1d-0e9f8a7b6c5d","messageId":"154d8b33-fb89-494f-b61b-705dc800dbcc","patientId":"2c3d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f","sender":"patient","message":"The redness has spread since this morning.","sentAt":"2026-10-21T04:34:54.527Z","replyPath":"/api/v1/clinical-cases/8a7b6c5d-4e3f-4a2b-9c1d-0e9f8a7b6c5d/messages"}}}}},"responses":{"200":{"description":"Durably received. Any `2xx` status counts; anything else is retried."}}}},"clinicalCaseAcknowledged":{"post":{"tags":["Webhooks"],"operationId":"clinicalCaseAcknowledgedWebhook","summary":"clinical_case.acknowledged","description":"Sent when a team member acknowledges the case in NezerCare. It isn't the same as your `processed` case update. The body is the same as `clinical_case.opened`, with the case's `status`.","parameters":[{"name":"x-nezer-event-id","in":"header","required":true,"description":"The event's ID, the same as the body's `id`. A retry of the delivery reuses it: deduplicate on it.","schema":{"type":"string","format":"uuid"}},{"name":"x-nezer-event-type","in":"header","required":true,"description":"The event's name, such as `clinical_case.opened`.","schema":{"type":"string"}},{"name":"x-nezer-timestamp","in":"header","required":true,"description":"When this attempt was signed, in seconds since the epoch. A retry is signed afresh.","schema":{"type":"string","pattern":"^[0-9]+$"}},{"name":"x-nezer-signature","in":"header","required":true,"description":"`v1=` and the lowercase hex HMAC-SHA256 of `<x-nezer-timestamp>.<raw request body>`, keyed with the endpoint's signing secret.","schema":{"type":"string","pattern":"^v1=[a-f0-9]{64}$"}},{"name":"idempotency-key","in":"header","required":true,"description":"The same value as `x-nezer-event-id`.","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClinicalCaseLifecycleEvent"}}}},"responses":{"200":{"description":"Durably received. Any `2xx` status counts; anything else is retried."}}}},"clinicalCaseResolved":{"post":{"tags":["Webhooks"],"operationId":"clinicalCaseResolvedWebhook","summary":"clinical_case.resolved","description":"Sent when a team member resolves the case in NezerCare. A resolution your own system reports with a `resolved` case update does not send it (you already know). The body is the same as `clinical_case.opened`, with the case's `status` and its `resolutionOutcome` and `resolutionNote`. A late delivery can describe a case your integration has already processed; deduplicate by event ID.","parameters":[{"name":"x-nezer-event-id","in":"header","required":true,"description":"The event's ID, the same as the body's `id`. A retry of the delivery reuses it: deduplicate on it.","schema":{"type":"string","format":"uuid"}},{"name":"x-nezer-event-type","in":"header","required":true,"description":"The event's name, such as `clinical_case.opened`.","schema":{"type":"string"}},{"name":"x-nezer-timestamp","in":"header","required":true,"description":"When this attempt was signed, in seconds since the epoch. A retry is signed afresh.","schema":{"type":"string","pattern":"^[0-9]+$"}},{"name":"x-nezer-signature","in":"header","required":true,"description":"`v1=` and the lowercase hex HMAC-SHA256 of `<x-nezer-timestamp>.<raw request body>`, keyed with the endpoint's signing secret.","schema":{"type":"string","pattern":"^v1=[a-f0-9]{64}$"}},{"name":"idempotency-key","in":"header","required":true,"description":"The same value as `x-nezer-event-id`.","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClinicalCaseLifecycleEvent"}}}},"responses":{"200":{"description":"Durably received. Any `2xx` status counts; anything else is retried."}}}},"patientDeleted":{"post":{"tags":["Webhooks"],"operationId":"patientDeletedWebhook","summary":"patient.deleted","description":"Emitted when the clinic deletes a patient's data in NezerCare (an owner or administrator, from the patient's page). Carries no health information: the patient's ID, the workspace ID (`environmentId`), a reason code and the time. Delete or close your copy of the record as your own policy requires; the patient's earlier events refer to IDs that no longer exist in NezerCare.","parameters":[{"name":"x-nezer-event-id","in":"header","required":true,"description":"The event's ID, the same as the body's `id`. A retry of the delivery reuses it: deduplicate on it.","schema":{"type":"string","format":"uuid"}},{"name":"x-nezer-event-type","in":"header","required":true,"description":"The event's name, such as `clinical_case.opened`.","schema":{"type":"string"}},{"name":"x-nezer-timestamp","in":"header","required":true,"description":"When this attempt was signed, in seconds since the epoch. A retry is signed afresh.","schema":{"type":"string","pattern":"^[0-9]+$"}},{"name":"x-nezer-signature","in":"header","required":true,"description":"`v1=` and the lowercase hex HMAC-SHA256 of `<x-nezer-timestamp>.<raw request body>`, keyed with the endpoint's signing secret.","schema":{"type":"string","pattern":"^v1=[a-f0-9]{64}$"}},{"name":"idempotency-key","in":"header","required":true,"description":"The same value as `x-nezer-event-id`.","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatientDeletedEvent"},"example":{"id":"9b1f2c3d-4e5f-4a6b-8c7d-0e1f2a3b4c5d","type":"patient.deleted","createdAt":"2026-10-01T15:04:05.000Z","data":{"patientId":"6cb4ccfc-2f1e-4d3a-9b8c-7d6e5f4a3b2c","environmentId":"1d2c3b4a-5e6f-4a7b-8c9d-0e1f2a3b4c5d","reason":"patient_request","deletedAt":"2026-10-01T15:04:05.000Z"}}}}},"responses":{"200":{"description":"Durably received. Any `2xx` status counts; anything else is retried."}}}},"billingUsageThresholdReached":{"post":{"tags":["Webhooks"],"operationId":"billingUsageThresholdReachedWebhook","summary":"billing.usage_threshold_reached","description":"An account event: use reached 80%, 95% or 100% of the month's credits, sent once each per month. No patient data, and never held for the BAA. An organization still on an older plan with a monthly active-patient limit gets it at 80% and 100% of that limit, with `unit: \"active_patients\"`.","parameters":[{"name":"x-nezer-event-id","in":"header","required":true,"description":"The event's ID, the same as the body's `id`. A retry of the delivery reuses it: deduplicate on it.","schema":{"type":"string","format":"uuid"}},{"name":"x-nezer-event-type","in":"header","required":true,"description":"The event's name, such as `clinical_case.opened`.","schema":{"type":"string"}},{"name":"x-nezer-timestamp","in":"header","required":true,"description":"When this attempt was signed, in seconds since the epoch. A retry is signed afresh.","schema":{"type":"string","pattern":"^[0-9]+$"}},{"name":"x-nezer-signature","in":"header","required":true,"description":"`v1=` and the lowercase hex HMAC-SHA256 of `<x-nezer-timestamp>.<raw request body>`, keyed with the endpoint's signing secret.","schema":{"type":"string","pattern":"^v1=[a-f0-9]{64}$"}},{"name":"idempotency-key","in":"header","required":true,"description":"The same value as `x-nezer-event-id`.","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillingUsageThresholdReachedEvent"},"example":{"id":"3f6c1b2a-8d4e-4f5a-9b6c-7d8e9f0a1b2c","type":"billing.usage_threshold_reached","createdAt":"2026-10-01T15:04:05.000Z","data":{"unit":"credits","threshold":80,"creditsUsed":2400,"monthlyCredits":3000,"remaining":600,"paused":false}}}}},"responses":{"200":{"description":"Durably received. Any `2xx` status counts; anything else is retried."}}}},"subscriptionUpdated":{"post":{"tags":["Webhooks"],"operationId":"subscriptionUpdatedWebhook","summary":"subscription.updated","description":"An account event: your subscription changed state (a payment, a failed payment, grace-period expiry, a cancellation, a first payment, or an Enterprise invoice paid or overdue). No patient data, and never held for the BAA.","parameters":[{"name":"x-nezer-event-id","in":"header","required":true,"description":"The event's ID, the same as the body's `id`. A retry of the delivery reuses it: deduplicate on it.","schema":{"type":"string","format":"uuid"}},{"name":"x-nezer-event-type","in":"header","required":true,"description":"The event's name, such as `clinical_case.opened`.","schema":{"type":"string"}},{"name":"x-nezer-timestamp","in":"header","required":true,"description":"When this attempt was signed, in seconds since the epoch. A retry is signed afresh.","schema":{"type":"string","pattern":"^[0-9]+$"}},{"name":"x-nezer-signature","in":"header","required":true,"description":"`v1=` and the lowercase hex HMAC-SHA256 of `<x-nezer-timestamp>.<raw request body>`, keyed with the endpoint's signing secret.","schema":{"type":"string","pattern":"^v1=[a-f0-9]{64}$"}},{"name":"idempotency-key","in":"header","required":true,"description":"The same value as `x-nezer-event-id`.","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionUpdatedEvent"},"example":{"id":"7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d","type":"subscription.updated","createdAt":"2026-10-01T15:04:05.000Z","data":{"status":"restricted","plan":null,"reason":"PAYMENT_GRACE_PERIOD_EXPIRED","recovered":false,"invoicePastDue":false}}}}},"responses":{"200":{"description":"Durably received. Any `2xx` status counts; anything else is retried."}}}},"integrationTest":{"post":{"tags":["Webhooks"],"operationId":"integrationTestWebhook","summary":"integration.test","description":"Sent only when someone on your team presses **Test connection** beside your address in Integrations → Connection health. You can't subscribe to it. It is built and signed exactly like a real event: the same headers, the signature from this address's own signing secret, and the address's login (an `Authorization` or API-key header) when it has one, so a receiver that verifies the signature or the login sees what a delivery would show it. It says it is a test (`data.test` is `true` and the `x-nezer-test` header is `true`), carries no patient data and creates nothing in NezerCare. Answer with any `2xx` and do nothing else with it; a `401` means your receiver didn't accept the signature or the login. It is sent once, never retried, to the public address only, and a redirect is not followed. Your team sees the answer's status in Connection health.","parameters":[{"name":"x-nezer-event-id","in":"header","required":true,"description":"The event's ID, the same as the body's `id`. A retry of the delivery reuses it: deduplicate on it.","schema":{"type":"string","format":"uuid"}},{"name":"x-nezer-event-type","in":"header","required":true,"description":"The event's name, such as `clinical_case.opened`.","schema":{"type":"string"}},{"name":"x-nezer-timestamp","in":"header","required":true,"description":"When this attempt was signed, in seconds since the epoch. A retry is signed afresh.","schema":{"type":"string","pattern":"^[0-9]+$"}},{"name":"x-nezer-signature","in":"header","required":true,"description":"`v1=` and the lowercase hex HMAC-SHA256 of `<x-nezer-timestamp>.<raw request body>`, keyed with the endpoint's signing secret.","schema":{"type":"string","pattern":"^v1=[a-f0-9]{64}$"}},{"name":"idempotency-key","in":"header","required":true,"description":"The same value as `x-nezer-event-id`.","schema":{"type":"string","format":"uuid"}},{"name":"x-nezer-test","in":"header","required":true,"description":"Always `true` on this event, so a receiver can tell a test from a delivery.","schema":{"type":"string","const":"true"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntegrationTestEvent"},"example":{"id":"0c9f6a41-2b7d-4e58-9a13-6f8d2c4b7e10","type":"integration.test","createdAt":"2026-10-24T14:05:00.000Z","data":{"test":true,"probeId":"0c9f6a41-2b7d-4e58-9a13-6f8d2c4b7e10","environmentId":"1d2c3b4a-5e6f-4a7b-8c9d-0e1f2a3b4c5d","sentAt":"2026-10-24T14:05:00.000Z","message":"This is a test from NezerCare's Test connection. It carries no patient data. Answer with any 2xx and do nothing else with it."}}}}},"responses":{"200":{"description":"Any `2xx` status counts as reachable. Anything else is shown to your team as the answer your system gave."}}}}},"components":{"securitySchemes":{"workforceAuth":{"type":"http","scheme":"bearer","bearerFormat":"Firebase workforce ID token","description":"Workforce setup only. Requires integrations.manage; mutations require MFA. A second factor used for the first time in the last 30 minutes isn't accepted for them yet (403 `SECOND_FACTOR_ON_HOLD`, with `heldUntil`). Not a NezerCare API key."},"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"NezerCare API key","description":"Paste the complete key (nzh_prod_…; a key made before October 2026 may start nzh_sb_…; a NezerCare setup test key starts nzh_test_… and sees test patients only). Paste the key alone into a tool's Bearer Token field (without the word Bearer); in a raw request the header is `Authorization: Bearer <key>`. Each route needs the key to have the scope it names (care_handoff, conversation_gateway, conversation_internal_notes for includeInternal=true, portal_messaging for patient messaging), chosen when the key is created; the last two are turned on by an owner or administrator."}},"schemas":{"WorkflowDefinition":{"type":"object","required":["category","description","steps"],"description":"Steps run in order unless one says where to go next. Anything that changes an account (a non-GET call not marked readOnly) must come after a call that checks ownership and after a Confirm step; a call using anything the patient typed must check ownership. Both are enforced again while running.","properties":{"schema":{"type":"integer","enum":[2]},"category":{"type":"string","enum":["support","billing","scheduling","fulfillment"]},"description":{"type":"string","minLength":1,"maxLength":300,"example":"Tells a patient where their order is."},"triggerPhrases":{"type":"array","maxItems":20,"items":{"type":"string","minLength":1,"maxLength":60}},"excludePhrases":{"type":"array","maxItems":20,"items":{"type":"string","minLength":1,"maxLength":60}},"steps":{"type":"array","minItems":1,"maxItems":30,"items":{"oneOf":[{"type":"object","required":["id","type","variable","prompt","format"],"properties":{"id":{"type":"string","pattern":"^[a-z][a-z0-9_]{0,39}$"},"type":{"type":"string","enum":["ask"]},"next":{"type":"string","maxLength":40,"description":"Another step's id, or \"end\"."},"variable":{"type":"string","pattern":"^[a-zA-Z][a-zA-Z0-9_]{0,39}$"},"prompt":{"type":"string","minLength":1,"maxLength":500,"description":"May use {{variable}}, {{patient.email}}, {{patient.externalId}} and {{run.id}}."},"format":{"type":"string","enum":["text","order_number","email","number","photos"],"description":"photos shows an upload button and saves how many files were added."},"label":{"type":"string","minLength":1,"maxLength":40,"example":"Medication","description":"Names the answer in the team's hand-off summary (\"Medication: …\"). Defaults to the variable name in words."}}},{"type":"object","required":["id","type","destinationStableKey","method","path","save","notFoundReply","errorReply"],"properties":{"id":{"type":"string","pattern":"^[a-z][a-z0-9_]{0,39}$"},"type":{"type":"string","enum":["call_api"]},"next":{"type":"string","maxLength":40,"description":"Another step's id, or \"end\"."},"destinationStableKey":{"type":"string","pattern":"^[a-z][a-z0-9_]{1,79}$"},"method":{"type":"string","enum":["GET","POST","PUT","PATCH","DELETE"]},"path":{"type":"string","maxLength":500,"example":"/orders/{{orderNumber}}","description":"Added to the connection's address; values are URL-encoded."},"body":{"type":"object","additionalProperties":true,"description":"JSON for non-GET calls, up to 8,000 characters. Credentials belong on the connection."},"readOnly":{"type":"boolean","description":"A non-GET call that only looks something up."},"select":{"type":"object","required":["listPath","matchPath","equals"],"properties":{"listPath":{"type":"string","maxLength":160,"description":"Dot path into the JSON response, like shipment.tracking."},"matchPath":{"type":"string","maxLength":160,"description":"Dot path into the JSON response, like shipment.tracking."},"equals":{"type":"string","minLength":1,"maxLength":200,"description":"May use {{variable}}, {{patient.email}}, {{patient.externalId}} and {{run.id}}."}}},"save":{"type":"array","maxItems":20,"items":{"type":"object","required":["variable","path"],"properties":{"variable":{"type":"string","pattern":"^[a-zA-Z][a-zA-Z0-9_]{0,39}$"},"path":{"type":"string","maxLength":160,"description":"Dot path into the JSON response, like shipment.tracking."}}}},"ownership":{"type":"object","properties":{"emailPath":{"type":"string","maxLength":160,"description":"Dot path into the JSON response, like shipment.tracking."},"patientIdPath":{"type":"string","maxLength":160,"description":"Dot path into the JSON response, like shipment.tracking."}},"description":"Where the response names its patient. A record that isn't theirs reads as not found."},"contract":{"type":"string","enum":["orders_v1"],"description":"Hold the answer to the order lookup contract (OrderLookupResponse). An answer that breaks it is treated as a failed call; no orders is treated as not found; otherwise the patient sees their latest orders as cards, and orderCount and latestOrderStatus are saved. Can't be combined with select."},"notFoundReply":{"type":"string","minLength":1,"maxLength":500,"description":"May use {{variable}}, {{patient.email}}, {{patient.externalId}} and {{run.id}}."},"errorReply":{"type":"string","minLength":1,"maxLength":500,"description":"May use {{variable}}, {{patient.email}}, {{patient.externalId}} and {{run.id}}."}}},{"type":"object","required":["id","type","variable","operator","then","else"],"properties":{"id":{"type":"string","pattern":"^[a-z][a-z0-9_]{0,39}$"},"type":{"type":"string","enum":["condition"]},"next":{"type":"string","maxLength":40,"description":"Another step's id, or \"end\"."},"variable":{"type":"string","pattern":"^[a-zA-Z][a-zA-Z0-9_]{0,39}$"},"operator":{"type":"string","enum":["equals","not_equals","contains","is_empty","is_not_empty"]},"value":{"type":"string","maxLength":200},"then":{"type":"string","maxLength":40,"description":"Another step's id, or \"end\"."},"else":{"type":"string","maxLength":40,"description":"Another step's id, or \"end\"."}}},{"type":"object","required":["id","type","prompt","declineReply"],"properties":{"id":{"type":"string","pattern":"^[a-z][a-z0-9_]{0,39}$"},"type":{"type":"string","enum":["confirm"]},"next":{"type":"string","maxLength":40,"description":"Another step's id, or \"end\"."},"prompt":{"type":"string","minLength":1,"maxLength":500,"description":"May use {{variable}}, {{patient.email}}, {{patient.externalId}} and {{run.id}}."},"declineReply":{"type":"string","minLength":1,"maxLength":500,"description":"May use {{variable}}, {{patient.email}}, {{patient.externalId}} and {{run.id}}."}}},{"type":"object","required":["id","type","message"],"properties":{"id":{"type":"string","pattern":"^[a-z][a-z0-9_]{0,39}$"},"type":{"type":"string","enum":["reply"]},"next":{"type":"string","maxLength":40,"description":"Another step's id, or \"end\"."},"message":{"type":"string","minLength":1,"maxLength":1000,"description":"May use {{variable}}, {{patient.email}}, {{patient.externalId}} and {{run.id}}."}}},{"type":"object","required":["id","type","message"],"properties":{"id":{"type":"string","pattern":"^[a-z][a-z0-9_]{0,39}$"},"type":{"type":"string","enum":["hand_off"]},"next":{"type":"string","maxLength":40,"description":"Another step's id, or \"end\"."},"message":{"type":"string","minLength":1,"maxLength":500,"description":"May use {{variable}}, {{patient.email}}, {{patient.externalId}} and {{run.id}}. The patient's acknowledgement. One that is still word for word a message a template has since replaced is said, listed and copied into a new draft in the template's current words; the version it's saved in isn't changed."},"summary":{"type":"string","minLength":1,"maxLength":500,"description":"May use {{variable}}, {{patient.email}}, {{patient.externalId}} and {{run.id}}."},"teamAsk":{"type":"string","minLength":1,"maxLength":300,"description":"May use {{variable}}, {{patient.email}}, {{patient.externalId}} and {{run.id}}."},"category":{"type":"string","enum":["support","billing","scheduling","fulfillment","clinical"],"description":"The team that gets it; defaults to the workflow's category. clinical is the care team (a refill request, for example). The patient isn't sent a second, generic acknowledgement after this step's message; staff see an internal summary of the patient's answers at the top of the conversation."}}}]}}}},"OrderLookupRequest":{"type":"object","required":["version","type","requestId","patient"],"description":"The template's body. A clinic may edit it in the builder; {{patient.externalId}} is the patient's ID in your system, the `sub` your site signs them in with (never what they typed).","properties":{"version":{"type":"integer","enum":[1]},"type":{"type":"string","enum":["order_lookup.requested"]},"requestId":{"type":"string","description":"The workflow run's id; the same for every call in one run."},"patient":{"type":"object","required":["externalId"],"properties":{"externalId":{"type":"string","example":"test-patient-1"}}}},"example":{"version":1,"type":"order_lookup.requested","requestId":"0f2c9a4e-3d7b-4c1e-9a55-000000000000","patient":{"externalId":"test-patient-1"}}},"OrderLookupResponse":{"type":"object","required":["orders"],"description":"Checked strictly: a wrong type, an unknown status or a malformed date makes the whole answer invalid. Fields not listed here are ignored. null means not given.","properties":{"orders":{"type":"array","maxItems":50,"items":{"$ref":"#/components/schemas/OrderLookupOrder"}}}},"OrderLookupOrder":{"type":"object","required":["id","status"],"properties":{"id":{"type":"string","minLength":1,"maxLength":64,"description":"Your order number, as the patient knows it. A string (not a number)."},"status":{"type":"string","enum":["processing","shipped","delivered","delayed","cancelled"]},"statusLabel":{"type":["string","null"],"minLength":1,"maxLength":80,"description":"Shown instead of the widget's own word for the status, as written. An empty string makes the whole answer invalid: leave the field out, or send null, when there is none."},"carrier":{"type":["string","null"],"minLength":1,"maxLength":60,"description":"An empty string makes the whole answer invalid: leave the field out, or send null, when there is none."},"trackingUrl":{"type":["string","null"],"minLength":1,"maxLength":2000,"description":"Shown as a Track package link only when it's https (and has no user name or password); otherwise dropped."},"estimatedDelivery":{"type":["string","null"],"description":"YYYY-MM-DD, or an ISO 8601 date-time with a time zone."},"placedAt":{"type":["string","null"],"description":"YYYY-MM-DD or ISO 8601. When every order has it, the widget sorts latest first; otherwise it keeps your order."},"items":{"type":["array","null"],"maxItems":20,"items":{"type":"object","required":["name","quantity"],"properties":{"name":{"type":"string","minLength":1,"maxLength":120},"quantity":{"type":"integer","minimum":1,"maximum":999}}}}}},"PatientSearchRequest":{"type":"object","required":["version","type","requestId","searchKey","filters","limit","cursor"],"description":"What NezerCare sends: your search's key and only its declared filters. No patient data and no free text.","properties":{"version":{"type":"integer","enum":[1]},"type":{"type":"string","enum":["patient_search.requested"]},"requestId":{"type":"string","format":"uuid","description":"The same for every page of one search."},"searchKey":{"type":"string","pattern":"^[a-z][a-z0-9_]{1,39}$","description":"Which of your searches this is, as set up in the staff app."},"filters":{"type":"object","additionalProperties":{"oneOf":[{"type":"string","maxLength":40,"description":"A choice's value, a code, or a date (YYYY-MM-DD)."},{"type":"object","required":["from","to"],"properties":{"from":{"type":"string","format":"date"},"to":{"type":"string","format":"date"}},"description":"A date range, both days included."}]},"description":"By filter key. A filter that isn't required may be absent."},"limit":{"type":"integer","enum":[50],"description":"Send at most this many patients per page."},"cursor":{"type":["string","null"],"maxLength":500,"description":"Your previous page's nextCursor; null for the first page."}},"example":{"version":1,"type":"patient_search.requested","requestId":"0f2c9a4e-3d7b-4c1e-9a55-000000000000","searchKey":"orders_shipped","filters":{"carrier":"ups","warehouse":"dallas","shippedOn":{"from":"2026-09-28","to":"2026-10-04"}},"limit":50,"cursor":null}},"PatientSearchResponse":{"type":"object","required":["patients","total"],"description":"Checked strictly: a body that isn't JSON, an ID that isn't a string shaped like one, more than `limit` patients, or a total below what was sent makes the whole answer invalid. Only the IDs are read; any other field (a name, an email) is ignored and never stored or logged. Send the same IDs your site signs patients in with (the `sub` of their widget sign-in): an ID that isn't one of your patients in Nezer gets no message, and Slack only says how many there were, never the IDs.","properties":{"patients":{"type":"array","maxItems":50,"items":{"type":"object","required":["id"],"properties":{"id":{"type":"string","minLength":1,"maxLength":80,"pattern":"^[\\p{L}\\p{N}][\\p{L}\\p{N}._:@+/#-]{0,79}$","description":"The patient's ID in your system (their external patient ID), with no spaces."}}}},"total":{"type":"integer","minimum":0,"maximum":1000000,"description":"How many patients match in all, at least the number sent. When NezerCare stops before the last page it's the number shown: over 50, @Nezer asks the team to narrow the search. Once every page is read, NezerCare counts the distinct IDs instead, so a patient sent twice (one per order) counts once."},"nextCursor":{"type":["string","null"],"maxLength":500,"description":"Present when there's another page; NezerCare sends it back as cursor."}}},"PatientSearchDefinition":{"type":"object","required":["searchKey","name","description","connectionId","path","filters"],"description":"A search as staff set it up. A name, description, key, path, filter or option that sounds like it's about patients' health is refused.","properties":{"searchKey":{"type":"string","pattern":"^[a-z][a-z0-9_]{1,39}$","example":"orders_shipped"},"name":{"type":"string","minLength":1,"maxLength":80,"example":"Orders shipped"},"description":{"type":"string","minLength":1,"maxLength":300,"example":"Patients whose order shipped, by carrier, warehouse and ship date."},"connectionId":{"type":"string","format":"uuid","description":"One of your own systems' connections (Destinations), not a provider network or escalation connection."},"path":{"type":"string","pattern":"^/[A-Za-z0-9._~/-]{0,199}$","example":"/patients/search"},"filters":{"type":"array","maxItems":8,"items":{"$ref":"#/components/schemas/PatientSearchFilter"}}}},"PatientSearchFilter":{"type":"object","required":["key","label","type"],"properties":{"key":{"type":"string","pattern":"^[a-z][a-zA-Z0-9_]{0,39}$","example":"warehouse"},"label":{"type":"string","minLength":1,"maxLength":60,"example":"Warehouse"},"type":{"type":"string","enum":["choice","date","date_range","code"],"description":"There is no free-text type."},"required":{"type":"boolean","default":true},"options":{"type":"array","minItems":1,"maxItems":20,"description":"Only for a choice.","items":{"type":"object","required":["value","label"],"properties":{"value":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9_.-]{0,39}$"},"label":{"type":"string","minLength":1,"maxLength":60}}},"example":[{"value":"dallas","label":"Dallas"},{"value":"reno","label":"Reno"}]}}},"PatientIdentifyRequest":{"type":"object","required":["externalPatientId"],"properties":{"externalPatientId":{"type":"string","minLength":1,"maxLength":200,"description":"Your permanent ID for the patient. The same ID reaches the same patient from the widget."},"givenName":{"type":"string","maxLength":80,"description":"Required the first time (1 to 80 characters)."},"familyName":{"type":"string","maxLength":80},"email":{"type":"string","format":"email","maxLength":254,"description":"Required the first time."},"phone":{"type":"string","minLength":7,"maxLength":30}}},"PatientIdentifyResponse":{"type":"object","required":["patientId","externalPatientId","created","status"],"properties":{"patientId":{"type":"string","format":"uuid","description":"Keep it: every other call names it in the path."},"externalPatientId":{"type":"string"},"created":{"type":"boolean","description":"Whether this call added the patient."},"status":{"type":"string","enum":["active"]}}},"StartConversationRequest":{"type":"object","required":["requestId","text"],"properties":{"requestId":{"type":"string","format":"uuid","description":"Generate one per message. The same one again returns the same conversation and the same replies."},"externalConversationId":{"type":"string","minLength":1,"maxLength":200,"description":"Your own ID for the conversation, unique in the workspace, so you can map it without storing ours."},"language":{"type":"string","enum":["en","es"],"description":"The portal's screen language. The reply follows the message's own language when it is clearly English or Spanish."},"text":{"type":"string","minLength":1,"maxLength":10000,"description":"The patient's words, exactly as typed: don't filter, hold or edit them first."}}},"PatientMessageRequest":{"type":"object","required":["requestId"],"description":"Exactly one of `text` and `choiceId`.","properties":{"requestId":{"type":"string","format":"uuid"},"text":{"type":"string","minLength":1,"maxLength":10000},"choiceId":{"type":"string","enum":["helpful","talk_to_team","yes","no","unsure","send","send_now","done","skip"],"description":"A button the message under it offers (its `choices`, or the `choices` of its `input`). Needs `inReplyTo`."},"inReplyTo":{"type":"string","format":"uuid","description":"The message the button is under. Pressing a button on a message that is not the latest, or that doesn't offer it, is `409 STALE_ANSWER`."},"attachments":{"type":"array","maxItems":10,"description":"Files the patient added to this conversation first (see Add a photo or PDF). Each must be theirs, in this conversation or its run: otherwise `404 ATTACHMENT_NOT_FOUND`.","items":{"type":"object","required":["id"],"properties":{"id":{"type":"string","format":"uuid"}}}},"language":{"type":"string","enum":["en","es"]}}},"PortalMessage":{"description":"One message of a conversation. `text` is always the words to show; the rest depends on `kind`.","oneOf":[{"$ref":"#/components/schemas/PortalTextMessage"},{"$ref":"#/components/schemas/PortalAnswerMessage"},{"$ref":"#/components/schemas/PortalQuestionMessage"},{"$ref":"#/components/schemas/PortalReviewMessage"},{"$ref":"#/components/schemas/PortalOrdersMessage"},{"$ref":"#/components/schemas/PortalEmergencyMessage"},{"$ref":"#/components/schemas/PortalHandoffMessage"},{"$ref":"#/components/schemas/PortalNoticeMessage"},{"$ref":"#/components/schemas/PortalClosedMessage"}],"discriminator":{"propertyName":"kind"}},"PortalTextMessage":{"description":"`text`: the patient's message, or a reply from the care team (`from.kind: care_team`).","allOf":[{"type":"object","required":["id","sequence","kind","from","priority","language","text","createdAt"],"properties":{"id":{"type":"string","format":"uuid","description":"For the patient's own message, the `requestId` they sent."},"sequence":{"type":"integer","minimum":1,"description":"Position in the conversation: 1, 2, 3 with no gaps. Order by this."},"kind":{"type":"string","enum":["text","answer","question","review","emergency","handoff","notice","orders","closed"]},"from":{"type":"object","required":["kind","label"],"properties":{"kind":{"type":"string","enum":["patient","nezer","care_team","system"],"description":"`nezer` is the assistant and NezerCare's fixed notices; `care_team` is a person on the clinic's team, or the clinic's own system posting a reply."},"label":{"type":"string","description":"The words to show: \"You\", \"NezerCare\", \"Care team\" (Spanish \"Usted\", \"NezerCare\", \"Equipo médico\"). Staff names are never sent."}}},"priority":{"type":"string","enum":["normal","emergency"]},"language":{"type":"string","enum":["en","es"],"description":"The language of `text`."},"text":{"type":"string","description":"Always present: the words to show. A portal that renders nothing else can print `text` and stay correct. Never rewrite it."},"causedByRequestId":{"type":"string","format":"uuid","description":"The patient request this message answers, when it answers one."},"attachments":{"type":"array","description":"On a patient's message: the files they listed with it, as metadata (never the contents).","items":{"$ref":"#/components/schemas/PortalAttachmentSummary"}},"createdAt":{"type":"string","format":"date-time"}}}]},"PortalAnswerMessage":{"description":"`answer`: an everyday question answered from the clinic's own knowledge.","allOf":[{"type":"object","required":["id","sequence","kind","from","priority","language","text","createdAt"],"properties":{"id":{"type":"string","format":"uuid","description":"For the patient's own message, the `requestId` they sent."},"sequence":{"type":"integer","minimum":1,"description":"Position in the conversation: 1, 2, 3 with no gaps. Order by this."},"kind":{"type":"string","enum":["text","answer","question","review","emergency","handoff","notice","orders","closed"]},"from":{"type":"object","required":["kind","label"],"properties":{"kind":{"type":"string","enum":["patient","nezer","care_team","system"],"description":"`nezer` is the assistant and NezerCare's fixed notices; `care_team` is a person on the clinic's team, or the clinic's own system posting a reply."},"label":{"type":"string","description":"The words to show: \"You\", \"NezerCare\", \"Care team\" (Spanish \"Usted\", \"NezerCare\", \"Equipo médico\"). Staff names are never sent."}}},"priority":{"type":"string","enum":["normal","emergency"]},"language":{"type":"string","enum":["en","es"],"description":"The language of `text`."},"text":{"type":"string","description":"Always present: the words to show. A portal that renders nothing else can print `text` and stay correct. Never rewrite it."},"causedByRequestId":{"type":"string","format":"uuid","description":"The patient request this message answers, when it answers one."},"attachments":{"type":"array","description":"On a patient's message: the files they listed with it, as metadata (never the contents).","items":{"$ref":"#/components/schemas/PortalAttachmentSummary"}},"createdAt":{"type":"string","format":"date-time"}}},{"type":"object","required":["answerId","sources","actions","choices"],"properties":{"answerId":{"type":"string","format":"uuid"},"sources":{"type":"array","items":{"type":"object","required":["title","url"],"properties":{"title":{"type":"string"},"url":{"type":["string","null"],"format":"uri"}}},"description":"Where the answer came from. Show them."},"actions":{"type":"array","description":"At most a Book button, with an https address on the clinic's site. Never a contact button for a signed-in patient.","items":{"type":"object","required":["kind","url"],"properties":{"kind":{"type":"string","enum":["book"]},"url":{"type":"string","format":"uri"},"label":{"type":"string","enum":["demo","appointment","consultation","call"]}}}},"choices":{"type":"array","description":"The buttons under the answer: send the `id` as `choiceId`.","items":{"type":"object","required":["id","label"],"properties":{"id":{"type":"string","enum":["helpful","talk_to_team"]},"label":{"type":"string"}}}}}}]},"PortalChoice":{"type":"object","required":["id","label"],"properties":{"id":{"type":"string","enum":["helpful","talk_to_team","yes","no","unsure","send","send_now","done","skip"],"description":"Send it as `choiceId`."},"label":{"type":"string","description":"The words on the button, in the message's language."}}},"PortalQuestionMessage":{"description":"`question`: NezerCare asks the patient something, with fixed or clinic-approved words (never an AI's). `purpose` says why: `safety_check` (a yes, no or not sure to a safety check the clinic wrote), `intake` (an approved question of the Health concerns intake), `team_chat` (the guided chat for billing, scheduling, fulfillment and support) or `workflow` (a workflow run's ask, or the offer of a person when it ended). The patient answers by button (`choiceId`) or, unless `input` is photos, in words.","allOf":[{"type":"object","required":["id","sequence","kind","from","priority","language","text","createdAt"],"properties":{"id":{"type":"string","format":"uuid","description":"For the patient's own message, the `requestId` they sent."},"sequence":{"type":"integer","minimum":1,"description":"Position in the conversation: 1, 2, 3 with no gaps. Order by this."},"kind":{"type":"string","enum":["text","answer","question","review","emergency","handoff","notice","orders","closed"]},"from":{"type":"object","required":["kind","label"],"properties":{"kind":{"type":"string","enum":["patient","nezer","care_team","system"],"description":"`nezer` is the assistant and NezerCare's fixed notices; `care_team` is a person on the clinic's team, or the clinic's own system posting a reply."},"label":{"type":"string","description":"The words to show: \"You\", \"NezerCare\", \"Care team\" (Spanish \"Usted\", \"NezerCare\", \"Equipo médico\"). Staff names are never sent."}}},"priority":{"type":"string","enum":["normal","emergency"]},"language":{"type":"string","enum":["en","es"],"description":"The language of `text`."},"text":{"type":"string","description":"Always present: the words to show. A portal that renders nothing else can print `text` and stay correct. Never rewrite it."},"causedByRequestId":{"type":"string","format":"uuid","description":"The patient request this message answers, when it answers one."},"attachments":{"type":"array","description":"On a patient's message: the files they listed with it, as metadata (never the contents).","items":{"$ref":"#/components/schemas/PortalAttachmentSummary"}},"createdAt":{"type":"string","format":"date-time"}}},{"type":"object","required":["purpose","input"],"properties":{"purpose":{"type":"string","enum":["safety_check","intake","team_chat","workflow"]},"input":{"type":"object","required":["type"],"description":"`choice`: pick one of `choices`. `text`: answer in words (up to `maxLength`). `attachments`: add photos with the attachments call, then press `done` (or `skip`).","properties":{"type":{"type":"string","enum":["choice","text","attachments"]},"maxLength":{"type":"integer","example":2000},"choices":{"type":"array","items":{"$ref":"#/components/schemas/PortalChoice"}}}},"choices":{"type":"array","description":"Shortcuts beside the question: `send_now` (\"Send to my care team now\", for an urgent concern, at any point) or `done` and `skip` for photos.","items":{"$ref":"#/components/schemas/PortalChoice"}}}}]},"PortalReviewMessage":{"description":"`review`: \"Does this look right?\" with the summary of what the patient said (their own words for a health concern). The button `send` puts it with the care team; typing instead is a correction, which rewrites the summary.","allOf":[{"type":"object","required":["id","sequence","kind","from","priority","language","text","createdAt"],"properties":{"id":{"type":"string","format":"uuid","description":"For the patient's own message, the `requestId` they sent."},"sequence":{"type":"integer","minimum":1,"description":"Position in the conversation: 1, 2, 3 with no gaps. Order by this."},"kind":{"type":"string","enum":["text","answer","question","review","emergency","handoff","notice","orders","closed"]},"from":{"type":"object","required":["kind","label"],"properties":{"kind":{"type":"string","enum":["patient","nezer","care_team","system"],"description":"`nezer` is the assistant and NezerCare's fixed notices; `care_team` is a person on the clinic's team, or the clinic's own system posting a reply."},"label":{"type":"string","description":"The words to show: \"You\", \"NezerCare\", \"Care team\" (Spanish \"Usted\", \"NezerCare\", \"Equipo médico\"). Staff names are never sent."}}},"priority":{"type":"string","enum":["normal","emergency"]},"language":{"type":"string","enum":["en","es"],"description":"The language of `text`."},"text":{"type":"string","description":"Always present: the words to show. A portal that renders nothing else can print `text` and stay correct. Never rewrite it."},"causedByRequestId":{"type":"string","format":"uuid","description":"The patient request this message answers, when it answers one."},"attachments":{"type":"array","description":"On a patient's message: the files they listed with it, as metadata (never the contents).","items":{"$ref":"#/components/schemas/PortalAttachmentSummary"}},"createdAt":{"type":"string","format":"date-time"}}},{"type":"object","required":["status","summary","choices","input"],"properties":{"status":{"type":"string","enum":["ready","urgent"]},"summary":{"type":"string"},"choices":{"type":"array","items":{"$ref":"#/components/schemas/PortalChoice"}},"input":{"type":"object","properties":{"type":{"type":"string","enum":["text"]},"maxLength":{"type":"integer"},"hint":{"type":"string","example":"Need to change something?"}}}}}]},"PortalOrdersMessage":{"description":"`orders`: the patient's latest orders (at most three, newest first) from the clinic's own order system, found by a workflow. `text` has them in words; show cards from `orders`. Tracking links are always https.","allOf":[{"type":"object","required":["id","sequence","kind","from","priority","language","text","createdAt"],"properties":{"id":{"type":"string","format":"uuid","description":"For the patient's own message, the `requestId` they sent."},"sequence":{"type":"integer","minimum":1,"description":"Position in the conversation: 1, 2, 3 with no gaps. Order by this."},"kind":{"type":"string","enum":["text","answer","question","review","emergency","handoff","notice","orders","closed"]},"from":{"type":"object","required":["kind","label"],"properties":{"kind":{"type":"string","enum":["patient","nezer","care_team","system"],"description":"`nezer` is the assistant and NezerCare's fixed notices; `care_team` is a person on the clinic's team, or the clinic's own system posting a reply."},"label":{"type":"string","description":"The words to show: \"You\", \"NezerCare\", \"Care team\" (Spanish \"Usted\", \"NezerCare\", \"Equipo médico\"). Staff names are never sent."}}},"priority":{"type":"string","enum":["normal","emergency"]},"language":{"type":"string","enum":["en","es"],"description":"The language of `text`."},"text":{"type":"string","description":"Always present: the words to show. A portal that renders nothing else can print `text` and stay correct. Never rewrite it."},"causedByRequestId":{"type":"string","format":"uuid","description":"The patient request this message answers, when it answers one."},"attachments":{"type":"array","description":"On a patient's message: the files they listed with it, as metadata (never the contents).","items":{"$ref":"#/components/schemas/PortalAttachmentSummary"}},"createdAt":{"type":"string","format":"date-time"}}},{"type":"object","required":["orders"],"properties":{"orders":{"type":"array","items":{"type":"object","required":["id","status","items"],"properties":{"id":{"type":"string"},"status":{"type":"string","enum":["processing","shipped","delivered","delayed","cancelled"]},"statusLabel":{"type":["string","null"]},"carrier":{"type":["string","null"]},"trackingUrl":{"type":["string","null"],"format":"uri"},"estimatedDelivery":{"type":["string","null"]},"placedAt":{"type":["string","null"]},"items":{"type":"array","items":{"type":"object","required":["name","quantity"],"properties":{"name":{"type":"string"},"quantity":{"type":"integer"}}}}}}}}}]},"PortalAttachmentSummary":{"type":"object","required":["id","fileName","contentType","sizeBytes"],"properties":{"id":{"type":"string","format":"uuid"},"fileName":{"type":"string"},"contentType":{"type":"string","enum":["image/jpeg","image/png","image/webp","image/heic","application/pdf"]},"sizeBytes":{"type":"integer"}}},"PortalAttachment":{"type":"object","required":["id","fileName","contentType","sizeBytes","sha256"],"properties":{"id":{"type":"string","format":"uuid","description":"List it in the patient's next message."},"fileName":{"type":"string","description":"The name cleaned of any path, with the real extension."},"contentType":{"type":"string","enum":["image/jpeg","image/png","image/webp","image/heic","application/pdf"],"description":"From the file's first bytes."},"sizeBytes":{"type":"integer","description":"Of the file as stored, after cleaning."},"sha256":{"type":"string","description":"Of the file as stored, after cleaning: for a photo it is not the hash of the bytes you sent (a photo is saved again without its metadata); for a PDF it is."}}},"PortalEmergencyMessage":{"description":"`emergency`: the fixed, reviewed 911 guidance. Always `priority: \"emergency\"` and the lowest sequence of its turn. Show it the moment you receive it, in full, in these words.","allOf":[{"type":"object","required":["id","sequence","kind","from","priority","language","text","createdAt"],"properties":{"id":{"type":"string","format":"uuid","description":"For the patient's own message, the `requestId` they sent."},"sequence":{"type":"integer","minimum":1,"description":"Position in the conversation: 1, 2, 3 with no gaps. Order by this."},"kind":{"type":"string","enum":["text","answer","question","review","emergency","handoff","notice","orders","closed"]},"from":{"type":"object","required":["kind","label"],"properties":{"kind":{"type":"string","enum":["patient","nezer","care_team","system"],"description":"`nezer` is the assistant and NezerCare's fixed notices; `care_team` is a person on the clinic's team, or the clinic's own system posting a reply."},"label":{"type":"string","description":"The words to show: \"You\", \"NezerCare\", \"Care team\" (Spanish \"Usted\", \"NezerCare\", \"Equipo médico\"). Staff names are never sent."}}},"priority":{"type":"string","enum":["normal","emergency"]},"language":{"type":"string","enum":["en","es"],"description":"The language of `text`."},"text":{"type":"string","description":"Always present: the words to show. A portal that renders nothing else can print `text` and stay correct. Never rewrite it."},"causedByRequestId":{"type":"string","format":"uuid","description":"The patient request this message answers, when it answers one."},"attachments":{"type":"array","description":"On a patient's message: the files they listed with it, as metadata (never the contents).","items":{"$ref":"#/components/schemas/PortalAttachmentSummary"}},"createdAt":{"type":"string","format":"date-time"}}},{"type":"object","required":["emergency"],"properties":{"emergency":{"type":"object","required":["lines","sentToCareTeam"],"properties":{"lines":{"type":"array","items":{"$ref":"#/components/schemas/PortalCallLine"},"description":"The ways to call. Thoughts of self-harm add 988."},"sentToCareTeam":{"type":"boolean","description":"Whether it reached the care team (an emergency case, or the clinical conversation). `false` means NezerCare could not file it yet and keeps trying until it does; the notice is shown either way, in the same words."}}}}}]},"PortalHandoffMessage":{"description":"`handoff`: it reached the team: a message sent straight to them, a health concern or request the patient reviewed and sent (or, for an urgent concern the patient walked away from, that NezerCare filed for them), or a workflow that handed off (then `text` is the clinic's own hand-off words).","allOf":[{"type":"object","required":["id","sequence","kind","from","priority","language","text","createdAt"],"properties":{"id":{"type":"string","format":"uuid","description":"For the patient's own message, the `requestId` they sent."},"sequence":{"type":"integer","minimum":1,"description":"Position in the conversation: 1, 2, 3 with no gaps. Order by this."},"kind":{"type":"string","enum":["text","answer","question","review","emergency","handoff","notice","orders","closed"]},"from":{"type":"object","required":["kind","label"],"properties":{"kind":{"type":"string","enum":["patient","nezer","care_team","system"],"description":"`nezer` is the assistant and NezerCare's fixed notices; `care_team` is a person on the clinic's team, or the clinic's own system posting a reply."},"label":{"type":"string","description":"The words to show: \"You\", \"NezerCare\", \"Care team\" (Spanish \"Usted\", \"NezerCare\", \"Equipo médico\"). Staff names are never sent."}}},"priority":{"type":"string","enum":["normal","emergency"]},"language":{"type":"string","enum":["en","es"],"description":"The language of `text`."},"text":{"type":"string","description":"Always present: the words to show. A portal that renders nothing else can print `text` and stay correct. Never rewrite it."},"causedByRequestId":{"type":"string","format":"uuid","description":"The patient request this message answers, when it answers one."},"attachments":{"type":"array","description":"On a patient's message: the files they listed with it, as metadata (never the contents).","items":{"$ref":"#/components/schemas/PortalAttachmentSummary"}},"createdAt":{"type":"string","format":"date-time"}}},{"type":"object","required":["handoff"],"properties":{"handoff":{"type":"object","required":["reference","team","urgency"],"properties":{"reference":{"type":"string","pattern":"^NC-[0-9A-F]{8}$","description":"Something the patient and the team can both quote."},"team":{"type":"string","enum":["clinical","billing","scheduling","fulfillment","support"]},"urgency":{"type":"string","enum":["routine","urgent"]}}}}}]},"PortalNoticeMessage":{"description":"`notice`: a fixed notice. `paused`: replies from this clinic may be delayed (the workspace's trial ended or it is out of credits). The patient's message was still taken.","allOf":[{"type":"object","required":["id","sequence","kind","from","priority","language","text","createdAt"],"properties":{"id":{"type":"string","format":"uuid","description":"For the patient's own message, the `requestId` they sent."},"sequence":{"type":"integer","minimum":1,"description":"Position in the conversation: 1, 2, 3 with no gaps. Order by this."},"kind":{"type":"string","enum":["text","answer","question","review","emergency","handoff","notice","orders","closed"]},"from":{"type":"object","required":["kind","label"],"properties":{"kind":{"type":"string","enum":["patient","nezer","care_team","system"],"description":"`nezer` is the assistant and NezerCare's fixed notices; `care_team` is a person on the clinic's team, or the clinic's own system posting a reply."},"label":{"type":"string","description":"The words to show: \"You\", \"NezerCare\", \"Care team\" (Spanish \"Usted\", \"NezerCare\", \"Equipo médico\"). Staff names are never sent."}}},"priority":{"type":"string","enum":["normal","emergency"]},"language":{"type":"string","enum":["en","es"],"description":"The language of `text`."},"text":{"type":"string","description":"Always present: the words to show. A portal that renders nothing else can print `text` and stay correct. Never rewrite it."},"causedByRequestId":{"type":"string","format":"uuid","description":"The patient request this message answers, when it answers one."},"attachments":{"type":"array","description":"On a patient's message: the files they listed with it, as metadata (never the contents).","items":{"$ref":"#/components/schemas/PortalAttachmentSummary"}},"createdAt":{"type":"string","format":"date-time"}}},{"type":"object","required":["notice"],"properties":{"notice":{"type":"object","required":["code"],"properties":{"code":{"type":"string","enum":["paused"]}}}}}]},"PortalClosedMessage":{"description":"`closed`: the care team resolved the case or closed the conversation. Never the resolution note.","allOf":[{"type":"object","required":["id","sequence","kind","from","priority","language","text","createdAt"],"properties":{"id":{"type":"string","format":"uuid","description":"For the patient's own message, the `requestId` they sent."},"sequence":{"type":"integer","minimum":1,"description":"Position in the conversation: 1, 2, 3 with no gaps. Order by this."},"kind":{"type":"string","enum":["text","answer","question","review","emergency","handoff","notice","orders","closed"]},"from":{"type":"object","required":["kind","label"],"properties":{"kind":{"type":"string","enum":["patient","nezer","care_team","system"],"description":"`nezer` is the assistant and NezerCare's fixed notices; `care_team` is a person on the clinic's team, or the clinic's own system posting a reply."},"label":{"type":"string","description":"The words to show: \"You\", \"NezerCare\", \"Care team\" (Spanish \"Usted\", \"NezerCare\", \"Equipo médico\"). Staff names are never sent."}}},"priority":{"type":"string","enum":["normal","emergency"]},"language":{"type":"string","enum":["en","es"],"description":"The language of `text`."},"text":{"type":"string","description":"Always present: the words to show. A portal that renders nothing else can print `text` and stay correct. Never rewrite it."},"causedByRequestId":{"type":"string","format":"uuid","description":"The patient request this message answers, when it answers one."},"attachments":{"type":"array","description":"On a patient's message: the files they listed with it, as metadata (never the contents).","items":{"$ref":"#/components/schemas/PortalAttachmentSummary"}},"createdAt":{"type":"string","format":"date-time"}}},{"type":"object","required":["closed"],"properties":{"closed":{"type":"object","required":["reason"],"properties":{"reason":{"type":"string","enum":["closed"]}}}}}]},"PortalCallLine":{"type":"object","required":["label","tel"],"properties":{"label":{"type":"string","example":"Call 911"},"tel":{"type":"string","example":"tel:911"}}},"PortalEmergency":{"type":"object","description":"The 911 guidance, repeated at the top of a response (and of an error) to a message that was an emergency.","required":["language","message","lines"],"properties":{"language":{"type":"string","enum":["en","es"]},"message":{"type":"string","description":"The reviewed emergency text, in the language the patient wrote in, or the clinic's own message for its extra emergency phrases."},"lines":{"type":"array","items":{"$ref":"#/components/schemas/PortalCallLine"}}}},"PortalConversation":{"type":"object","required":["id","patientId","channel","status","careStatus","appointment","showCall911","awaiting","lastSequence","version","language","safety","createdAt","updatedAt"],"properties":{"id":{"type":"string","format":"uuid"},"patientId":{"type":"string","format":"uuid"},"externalConversationId":{"type":["string","null"]},"channel":{"type":"string","enum":["portal_api"]},"status":{"type":"string","enum":["open","closed"]},"careStatus":{"type":"object","required":["code","label"],"description":"Where the conversation stands, in the widget's own words only.","properties":{"code":{"type":"string","enum":["received","in_progress","replied","scheduled","closed"]},"label":{"type":"string","example":"New reply from your care team"}}},"appointment":{"description":"The appointment of the case this conversation is linked to, for your portal to show its patient, or `null`. It is there from booking until an hour after the start, and not once the case is closed or the appointment cancelled. In a response it carries `visitUrl`, the link that opens the visit; **a webhook's `appointment` never does**: read the conversation for it. The link lets whoever has it join the visit: show it to this patient only, and don't log it or put it in a URL. How an appointment is booked is in the Clinical cases operation `updateClinicalCase`.","oneOf":[{"type":"null"},{"type":"object","required":["scheduledFor"],"properties":{"scheduledFor":{"type":"string","format":"date-time","description":"The start, in UTC (show it in the patient's own time zone)."},"visitUrl":{"type":["string","null"],"format":"uri","description":"The link to join the visit; `null` for an appointment booked before links were required; absent in a webhook."}}}]},"showCall911":{"type":"boolean","description":"True while an emergency conversation is open: keep the 911 guidance in view."},"awaiting":{"type":"object","required":["type"],"description":"A hint for the composer, never a lock: free text is always accepted.","properties":{"type":{"type":"string","enum":["none","choice","text","attachments"],"description":"What the latest message from NezerCare waits for: one of its buttons, words (with `choices` as shortcuts, if any), or photos (then `done` or `skip`)."},"messageId":{"type":"string","format":"uuid"},"choices":{"type":"array","items":{"type":"string"}}}},"lastSequence":{"type":"integer","minimum":0},"version":{"type":"integer","minimum":1,"description":"Increases whenever the conversation changes."},"language":{"type":"string","enum":["en","es"]},"safety":{"type":"object","required":["language","emergencyLine","lines"],"description":"The exact approved 911 line to print at all times where a patient can write or read messages, and the ways to call. Use these words rather than your own.","properties":{"language":{"type":"string","enum":["en","es"]},"emergencyLine":{"type":"string","example":"If this is a medical emergency, call 911."},"lines":{"type":"array","items":{"$ref":"#/components/schemas/PortalCallLine"}}}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"PatientTurnResponse":{"type":"object","required":["conversation","message","replies","showCall911","emergency","duplicate"],"properties":{"conversation":{"$ref":"#/components/schemas/PortalConversation"},"message":{"$ref":"#/components/schemas/PortalMessage"},"replies":{"type":"array","items":{"$ref":"#/components/schemas/PortalMessage"},"description":"NezerCare's messages for this one, in sequence order; an emergency notice is always first. Empty when the message went into a thread the care team already has."},"showCall911":{"type":"boolean","description":"True when the message was an emergency."},"emergency":{"oneOf":[{"$ref":"#/components/schemas/PortalEmergency"},{"type":"null"}]},"duplicate":{"type":"boolean","description":"True when this is the stored turn of a `requestId` already handled, or an emergency repeat answered with the 911 notice and not stored because the key is past its hourly ceiling for emergencies (see the message routes)."}}},"PortalMessageList":{"type":"object","required":["messages","lastSequence","hasMore","conversation"],"properties":{"messages":{"type":"array","items":{"$ref":"#/components/schemas/PortalMessage"}},"lastSequence":{"type":"integer","minimum":0,"description":"The conversation's newest sequence."},"hasMore":{"type":"boolean","description":"True when more messages follow the last one returned: ask again with its sequence."},"conversation":{"$ref":"#/components/schemas/PortalConversation"}}},"PortalConversationList":{"type":"object","required":["conversations","hasMore","nextCursor"],"properties":{"conversations":{"type":"array","items":{"$ref":"#/components/schemas/PortalConversation"},"description":"Newest activity first."},"hasMore":{"type":"boolean","description":"True when another page follows."},"nextCursor":{"type":["string","null"],"description":"Pass it as `after` for the next page. Opaque: never build one."}}},"PortalDeliveryRequest":{"type":"object","required":["status"],"properties":{"status":{"type":"string","enum":["delivered","read","failed"],"description":"What the screen did with the message."},"errorCode":{"type":"string","pattern":"^[A-Za-z0-9_.:-]{1,80}$","description":"With `failed` only: a short machine word for why. Never the patient's or the care team's words."},"externalMessageId":{"type":"string","minLength":1,"maxLength":200,"description":"Your own ID for your copy of the message, if you keep one."}}},"PortalDeliveryResponse":{"type":"object","required":["conversationId","messageId","status","duplicate","recordedAt"],"properties":{"conversationId":{"type":"string","format":"uuid"},"messageId":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["delivered","read","failed"]},"duplicate":{"type":"boolean","description":"True when this status was already recorded for the message."},"recordedAt":{"type":"string","format":"date-time","description":"When it was first recorded."}}},"PortalWebhookSubject":{"type":"object","required":["conversationId","externalConversationId","patientId","externalPatientId"],"properties":{"conversationId":{"type":"string","format":"uuid"},"externalConversationId":{"type":["string","null"],"description":"Your own ID for the conversation, if you sent one."},"patientId":{"type":"string","format":"uuid"},"externalPatientId":{"type":["string","null"],"description":"Your own ID for the patient, as you sent it to `identify`."}}},"PortalMessageCreatedEvent":{"allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","properties":{"type":{"type":"string","const":"conversation.message_created"},"data":{"allOf":[{"$ref":"#/components/schemas/PortalWebhookSubject"},{"type":"object","required":["sequence","message","conversation"],"properties":{"sequence":{"type":"integer","minimum":1,"description":"The message's position in the conversation. Apply messages by this, not by arrival."},"message":{"$ref":"#/components/schemas/PortalMessage","description":"Exactly the message the feed returns, with `causedByRequestId` when it answers a patient request."},"conversation":{"type":"object","required":["status","careStatus","showCall911","version"],"description":"The conversation as it stands when the event is sent, which can be newer than the message.","properties":{"status":{"type":"string","enum":["open","closed"]},"careStatus":{"type":"object","required":["code","label"],"properties":{"code":{"type":"string","enum":["received","in_progress","replied","scheduled","closed"]},"label":{"type":"string"}}},"showCall911":{"type":"boolean"},"version":{"type":"integer","minimum":1}}}}}]}}}]},"PortalConversationUpdatedEvent":{"allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","properties":{"type":{"type":"string","const":"conversation.updated"},"data":{"allOf":[{"$ref":"#/components/schemas/PortalWebhookSubject"},{"type":"object","required":["conversation"],"properties":{"conversation":{"$ref":"#/components/schemas/PortalConversation","description":"The conversation's state when the event is sent."}}}]}}}]},"PortalError":{"type":"object","required":["code","message"],"description":"The message is for the developer, never for the patient. An error to a message that was an emergency also carries `showCall911` and `emergency`.","properties":{"code":{"type":"string","description":"INVALID_REQUEST, PATIENT_PROFILE_REQUIRED, INVALID_API_CREDENTIAL, MISSING_API_CREDENTIAL, BAA_REQUIRED, INSUFFICIENT_SCOPE, PATIENT_NOT_FOUND, CONVERSATION_NOT_FOUND, MESSAGE_NOT_FOUND, ATTACHMENT_NOT_FOUND, ENVIRONMENT_RETIRED, REQUEST_ID_REUSED, CONVERSATION_CLOSED, STALE_ANSWER, TURN_IN_PROGRESS, PATIENT_INACTIVE, PATIENT_ID_UNAVAILABLE, EXTERNAL_CONVERSATION_ID_IN_USE, ATTACHMENT_NOT_EXPECTED, ATTACHMENT_LIMIT_REACHED, ATTACHMENT_TOO_LARGE, ATTACHMENT_TYPE_NOT_ALLOWED, ATTACHMENT_REJECTED, PATIENT_FILES_UNAVAILABLE, PATIENT_CAP_REACHED, RATE_LIMITED, INTERNAL_ERROR. A route's own 404 or 403 without one of these carries the generic NOT_FOUND or FORBIDDEN."},"message":{"type":"string"},"showCall911":{"type":"boolean"},"emergency":{"$ref":"#/components/schemas/PortalEmergency"}}},"ConversationMessageInput":{"type":"object","required":["requestId","message"],"properties":{"requestId":{"type":"string","format":"uuid","description":"Generated by you, once for each message; it becomes the message's `id`."},"message":{"type":"string","minLength":1,"maxLength":10000,"description":"Patient-visible: write nothing in it that a patient shouldn't read."},"externalMessageId":{"type":"string","minLength":1,"maxLength":200,"description":"Your own ID for the message, kept with it."},"attachments":{"type":"array","description":"Records of files you hold. NezerCare stores these details and no file.","items":{"type":"object","required":["id","fileName","contentType","sha256"],"properties":{"id":{"type":"string","format":"uuid"},"fileName":{"type":"string","minLength":1,"maxLength":200},"contentType":{"type":"string","maxLength":160,"example":"application/pdf"},"sha256":{"type":"string","pattern":"^[a-f0-9]{64}$","description":"The SHA-256 of the file's bytes, in lowercase hex."}}}}}},"ConversationMessage":{"type":"object","required":["id","conversationId","sequence","senderType","direction","message","visibility","attachments","createdAt"],"description":"One message of a conversation. It also carries your `organizationId` and `environmentId` and a `requestHash` (a digest NezerCare uses to recognize a retry): ignore them.","properties":{"id":{"type":"string","format":"uuid","description":"For a message sent by `requestId`, that `requestId`."},"conversationId":{"type":"string","format":"uuid"},"sequence":{"type":"integer","minimum":1,"description":"Position in the conversation. Order by this."},"senderType":{"type":"string","enum":["patient","workforce","external","system"],"description":"`patient` wrote it, `workforce` is a member of the care team, `external` is your system (through this API) and `system` is NezerCare's own message (an acknowledgement, the notice that a patient's health reply went to the care team, a hand-off summary)."},"senderId":{"type":"string","format":"uuid","description":"An ID of the sender, never a name: the patient's ID, the team member's, your key's, or the organization's for a `system` message."},"direction":{"type":"string","enum":["inbound","outbound"],"description":"`inbound` is from the patient or your system; `outbound` is to the patient."},"message":{"type":"string"},"externalMessageId":{"type":["string","null"]},"visibility":{"type":"string","enum":["patient","internal"],"description":"`internal` appears only with `includeInternal=true`."},"attachments":{"type":"array","items":{"type":"object","required":["id","fileName","contentType","sha256"],"properties":{"id":{"type":"string","format":"uuid"},"fileName":{"type":"string"},"contentType":{"type":"string"},"sha256":{"type":"string"}}}},"createdAt":{"type":"string","format":"date-time"}}},"ConversationMessageResult":{"type":"object","required":["conversationId","messageId","sequence","duplicate","createdAt"],"properties":{"conversationId":{"type":"string","format":"uuid"},"messageId":{"type":"string","format":"uuid","description":"The `requestId` you sent."},"sequence":{"type":"integer","minimum":1},"duplicate":{"type":"boolean","description":"True when this is the stored result of a `requestId` already handled."},"createdAt":{"type":"string","format":"date-time"}}},"ConversationDeliveryUpdate":{"type":"object","required":["externalMessageId","status"],"properties":{"externalMessageId":{"type":"string","minLength":1,"maxLength":200,"description":"Your own ID for your copy of the message."},"status":{"type":"string","enum":["delivered","read","failed"]},"errorCode":{"type":"string","minLength":1,"maxLength":80,"description":"A short machine word for why it failed. Never anyone's words."}}},"ConversationDeliveryResult":{"type":"object","required":["conversationId","messageId","status","updatedAt"],"properties":{"conversationId":{"type":"string","format":"uuid"},"messageId":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["delivered","read","failed"]},"updatedAt":{"type":"string","format":"date-time"}}},"Error":{"type":"object","required":["message"],"properties":{"code":{"type":"string","description":"A stable code for the cases that have one (for example `INVALID_API_CREDENTIAL`, `BAA_REQUIRED`, `INSUFFICIENT_SCOPE`, `RATE_LIMITED`, `ENVIRONMENT_RETIRED`, and on a case update `VISIT_URL_REQUIRED`, `VISIT_URL_INVALID`, `VISIT_URL_NOT_ALLOWED`, `NO_APPOINTMENT_TO_CANCEL`). Absent on a plain not-found, conflict or validation error: branch on the status then."},"message":{"type":["string","array"],"items":{"type":"string"},"description":"For you, never for a patient. A sentence, or a list of sentences (an array of strings) when a request failed validation."},"error":{"type":"string","description":"The status's name (`Not Found`, `Conflict`, `Bad Request`), on the errors that carry no `code`."},"statusCode":{"type":"integer","description":"The HTTP status, on the same errors."},"nextSequence":{"type":"integer","description":"On the `409` for an update out of sequence: the sequence to send."}}},"CaseProgress":{"type":"object","required":["caseId","status","sequence","nextSequence","confirmationOverdue","transportDelivered"],"properties":{"caseId":{"type":"string","format":"uuid"},"status":{"type":"string","description":"The latest update you reported (`processed`, `scheduled`, `appointment_cancelled`, `clinician_responded`, `patient_contacted` or `resolved`). Before you have reported one: `awaiting_processing` (the case was sent to your endpoint and you haven't sent `processed`) or `care_team_review` (it wasn't sent to any endpoint). `resolved` once the case is resolved, by you or by a team member in NezerCare. A routine case reads `self_care` until it is resolved, whatever you have reported."},"sequence":{"type":"integer","minimum":0,"description":"The sequence of the latest update; 0 before the first."},"nextSequence":{"type":"integer","minimum":1,"description":"The sequence the next update must use (`sequence` plus one). After the case is resolved, no update is accepted."},"confirmationOverdue":{"type":"boolean","description":"True when a case that isn't routine or resolved has had no update 15 minutes after its `clinical_case.opened` was first sent (or, for a clinic reached through a Destination, after the escalation was queued). A flag for NezerCare's team to follow up, not a promise about clinical response time."},"confirmationDueAt":{"type":["string","null"],"format":"date-time","description":"15 minutes after `clinical_case.opened` was first sent (or the escalation to a Destination was queued); null when neither ever was."},"transportDelivered":{"type":"boolean","description":"Whether a delivery of `clinical_case.opened`, or the escalation to a Destination, got a `2xx` answer. Transport only: it says nothing about processing or clinical review."},"scheduledFor":{"type":["string","null"],"format":"date-time","description":"The time of the case's appointment: the latest `scheduled` update you reported. It stays while you report what comes next (`clinician_responded`, `patient_contacted`), moves when you report another `scheduled` update, and is null before the first, once you send `appointment_cancelled`, and once the case is resolved."},"hasVisitLink":{"type":"boolean","description":"Whether that appointment has a visit link. The link itself is never returned here: you gave it."},"updatedAt":{"type":"string","format":"date-time"},"externalReference":{"type":["string","null"],"description":"The `externalReference` of the latest update."}}},"CaseUpdate":{"type":"object","required":["updateId","sequence","status","externalReference"],"properties":{"updateId":{"type":"string","format":"uuid","description":"Generated by you, once for each update. Reuse it only to retry the same update."},"sequence":{"type":"integer","minimum":1,"maximum":1000000,"description":"Must be exactly `nextSequence` from the progress endpoint; `409` otherwise."},"status":{"type":"string","description":"`processed` only as the first update, and the first update can only be `processed`.","enum":["processed","scheduled","appointment_cancelled","clinician_responded","patient_contacted","resolved"]},"externalReference":{"type":"string","minLength":1,"maxLength":200,"description":"Your own reference for the relevant conversation, appointment, message or case. Not shown to patients; never put a credential in it."},"scheduledFor":{"type":"string","format":"date-time","description":"A date and time with a time zone offset (`2026-09-08T14:30:00-04:00` or `…Z`). Required for `scheduled`, refused for any other status."},"visitUrl":{"type":"string","maxLength":2000,"format":"uri","pattern":"^https://","description":"The link the patient joins the visit with. **Required for `scheduled`** (and again on every move of the appointment), refused for any other status. `https` only, an ordinary public website name (not `localhost`, an IP address or a private name such as `.internal`), no username or password, no spaces or hidden characters, at most 2000 characters; otherwise `400` with `VISIT_URL_REQUIRED`, `VISIT_URL_INVALID` or `VISIT_URL_NOT_ALLOWED`. NezerCare stores it encrypted, shows it only to the patient of the case (a Join visit button in the widget, or `appointment` on the conversation of your own portal) and to staff who can work the case, and never puts it in an email, a webhook, a log or an audit event."},"resolutionOutcome":{"type":"string","description":"Required for `resolved`, refused for any other status.","enum":["patient_contacted","provider_follow_up","medication_adjusted","emergency_referral","no_further_action","other"]},"resolutionNote":{"type":"string","minLength":10,"maxLength":2000,"description":"Required for `resolved`, refused for any other status. Kept for the care team's review; not shown to the patient."}}},"CaseUpdateResult":{"type":"object","required":["caseId","updateId","sequence","status","duplicate"],"properties":{"caseId":{"type":"string","format":"uuid"},"updateId":{"type":"string","format":"uuid"},"sequence":{"type":"integer"},"status":{"type":"string"},"duplicate":{"type":"boolean"}}},"ProviderMessage":{"type":"object","required":["messageId","message","externalReference"],"properties":{"messageId":{"type":"string","format":"uuid"},"message":{"type":"string","minLength":1,"maxLength":4000},"externalReference":{"type":"string","minLength":1,"maxLength":200}}},"ProviderMessageResult":{"type":"object","required":["caseId","messageId","duplicate"],"properties":{"caseId":{"type":"string","format":"uuid"},"messageId":{"type":"string","format":"uuid"},"duplicate":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time","description":"When the message was stored. Left out of a retry's answer (`duplicate: true`)."}}},"CaseHandoff":{"type":"object","description":"Where to report back. The paths are the API's own and start with `/api/v1/...`: on `https://api.nezercare.com` call them without the `/api`. No API key is in the webhook.","properties":{"caseId":{"type":"string","format":"uuid"},"progressPath":{"type":"string","description":"`GET`: read the case's progress."},"updatesPath":{"type":"string","description":"`POST`: report progress."},"messagesPath":{"type":"string","description":"`POST`: write to the patient."},"firstStatus":{"type":"string","const":"processed","description":"The first update must have this status."},"firstSequence":{"type":"integer","const":1,"description":"The first update must have this sequence."},"transportReceiptIsClinicalAcceptance":{"type":"boolean","const":false,"description":"Always false: a `2xx` answer to this event confirms transport only."}}},"CaseIntake":{"type":"object","required":["language","questions","omittedQuestions"],"description":"The intake the patient went through before their concern became a case: the questions NezerCare asked and the patient's answers, in the order they were asked, so your system has what the care team sees in the conversation. Only what the patient saw and replied to: the words of your approved questions and safety checks as they read them, and what they sent back. Never the guide's summary or notes, the care team's messages or internal notes, another conversation, or anything after the case opened: a retry or a later event sends the same intake. For an emergency it holds what was asked before the emergency, if anything. It can hold protected health information: keep it out of ordinary logs. A case with no intake behind it (one a teammate raised from Slack, or one opened before October 24, 2026) has `language: null` and no questions.","properties":{"language":{"type":["string","null"],"enum":["en","es",null],"description":"The language of the questions and answers: the language the patient used the widget in. `null` when NezerCare has no record of an intake for the case."},"questions":{"type":"array","maxItems":50,"items":{"type":"object","required":["kind","question","answer"],"properties":{"kind":{"type":"string","enum":["follow_up","safety"],"description":"`follow_up`: one of your concern type's approved questions, or the closing \"anything else\" line. `safety`: one of its safety checks, a question with Yes, No and Not sure buttons."},"question":{"type":"string","maxLength":600,"description":"The question as the patient read it, in their language."},"answer":{"type":["string","null"],"maxLength":1000,"description":"What the patient replied, as they sent it: the button's label on a safety check (\"Yes\", \"No\", \"Sí\"), or their own words. `null` when the case was sent before they answered this question (they sent it early, or NezerCare filed an urgent case for them after ten minutes without a reply). An answer longer than 1,000 characters is cut and ends with `… [truncated]`; the whole reply stays in the case's conversation in NezerCare."},"choice":{"type":"string","enum":["yes","no","unsure"],"description":"Only on a safety check the patient answered with its Yes, No or Not sure button: which one, whatever the language. Left out when they typed an answer instead."}}}},"omittedQuestions":{"type":"integer","minimum":0,"description":"How many questions beyond the first 50 were left out. 0 in practice: an intake asks far fewer."}},"example":{"language":"en","questions":[{"kind":"safety","question":"Is the redness spreading quickly, or do you have a fever?","answer":"No","choice":"no"},{"kind":"follow_up","question":"When did you first notice it?","answer":"Two days ago, the evening after my Sunday dose."},{"kind":"follow_up","question":"Is it getting better, worse or staying the same?","answer":"Worse. It's about the size of a coin now and warm to the touch."}],"omittedQuestions":0}},"CaseEscalation":{"type":"object","required":["patientId","checkInId","disposition","matchedRules","notes","priority"],"description":"What NezerCare sends to a Destination when a case of a concern type that has one opens. The same fields as `clinical_case.opened` carries, under the names this send has always used.","properties":{"patientId":{"type":"string","format":"uuid"},"checkInId":{"type":"string","format":"uuid","description":"The submission's ID, the same as the `Idempotency-Key`. The name dates from check-ins; follow the case by `caseId`."},"caseId":{"type":"string","format":"uuid","description":"The case's own ID, for the calls below. Absent from an escalation queued before October 24, 2026."},"disposition":{"type":"string","enum":["emergency","clinical_escalation","self_care"],"description":"The older vocabulary; `priority` is the field to read."},"matchedRules":{"type":"array","items":{"type":"string"},"description":"Every red flag that matched, as on `clinical_case.opened`."},"notes":{"type":"string","description":"What the patient wrote: the concern type's name, a blank line and their first message. The same as `patientNotes` on `clinical_case.opened`."},"intake":{"$ref":"#/components/schemas/CaseIntake"},"priority":{"type":"string","enum":["emergency","urgent","routine"]},"handoff":{"$ref":"#/components/schemas/CaseHandoff"},"apiKey":{"type":"string","description":"Only when the Destination's authentication is \"API key in request body\": the key you saved on the Destination, added to every send (and retry) as this top-level field in place of a header. Absent for every other authentication. It is your own credential: verify it and keep it out of ordinary logs."}}},"WebhookEnvelope":{"type":"object","required":["id","type","createdAt","data"],"properties":{"id":{"type":"string","format":"uuid","description":"The event's ID, the same as the `x-nezer-event-id` header. Deduplicate on it."},"type":{"type":"string"},"createdAt":{"type":"string","format":"date-time","description":"When NezerCare queued this delivery to your endpoint."},"data":{"type":"object","additionalProperties":true}}},"ClinicalCaseOpenedEvent":{"allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","properties":{"type":{"type":"string","const":"clinical_case.opened"},"data":{"type":"object","required":["caseId","patientId","priority","handoff"],"properties":{"caseId":{"type":"string","format":"uuid"},"checkInId":{"type":"string","format":"uuid","description":"The ID of the record the case was opened from. The name dates from check-ins, which NezerCare no longer sends; follow the case by `caseId`."},"patientId":{"type":"string","format":"uuid"},"priority":{"type":"string","enum":["emergency","urgent","routine"],"description":"`emergency` when NezerCare's emergency rule, or one of your extra emergency phrases, matched what the patient wrote in the widget, including a reply in a case or conversation they already had (it opens a new emergency case for the patient, unless the patient already has an unresolved emergency case from the last 15 minutes: then the message is added to that case and delivered as `clinical_case.patient_message_created`, with no second `clinical_case.opened`). `routine` when the only red flags asked for a routine follow-up (for example, a medicine that isn't working). `urgent` also when a patient wrote about their health in a reply in a thread that isn't a health one (an order, a bill, a booking): nothing triaged it, so it is filed for urgent review, with their words as the case's first message. A `staff_slack` case is `urgent`, or `emergency` when the teammate's request used NezerCare's emergency words."},"source":{"type":"string","enum":["patient_concern","staff_slack"],"description":"Where the case came from: `patient_concern`, a concern a signed-in patient raised in the widget (or the emergency case opened for an emergency in a reply they sent in an existing thread, or the case opened for a health detail they wrote in a reply in an order, billing or booking thread, which never goes to your Slack), or `staff_slack`, a clinical request a teammate made of @Nezer in your Slack channel. A `staff_slack` case is raised by staff, not reported by the patient: `patientNotes` is empty and the teammate's words stay in NezerCare as an internal note on the case."},"patientNotes":{"type":["string","null"],"description":"What the patient wrote. Empty for a `staff_slack` case."},"symptomScores":{"type":"object","additionalProperties":{"type":"integer"},"deprecated":true,"description":"Always `{}`. Kept so receivers written when NezerCare sent check-ins keep working."},"matchedRules":{"type":"array","items":{"type":"string"},"description":"Every red flag that matched, not only the worst: `ai_intake:<concern key>` for the Health concern the patient's words matched, `deterministic_safety:<rule>` when one of NezerCare's own safety rules matched them, `health_concerns_phrase` when one of the extra emergency phrases on your Health concerns matched (the rule names no phrase and holds no patient text), `configured_safety_question` when an answer to one of your safety questions asked for an urgent review, `emergency_terms:<kind>` for NezerCare's emergency words in a teammate's request, and `staff_request:slack` on every case raised from Slack."},"healthConcerns":{"type":["object","null"],"description":"For a concern the patient raised in the widget: the version of your workspace's Health concerns it was triaged on. Version `0` is the NezerCare defaults, which run until a clinician on your team approves your own. `null` otherwise.","properties":{"version":{"type":"integer","minimum":0},"label":{"type":"string","examples":["Health concerns v3","NezerCare defaults"]}}},"status":{"type":"string","enum":["open","acknowledged","resolved"],"description":"The case's status when the event was built: `open` for a new case. Your `processed` and other updates don't change it; only a team member acknowledging or resolving it in NezerCare, or a `resolved` update, does."},"resolutionOutcome":{"type":["string","null"],"description":"Null until the case is resolved."},"resolutionNote":{"type":["string","null"],"description":"Null until the case is resolved."},"disposition":{"type":"string","enum":["emergency","clinical_escalation","self_care"],"description":"What the triage decided, in the older vocabulary: `emergency`, `clinical_escalation` or `self_care`. `priority` is the field to read."},"submittedAt":{"type":"string","format":"date-time","description":"When the concern the case was opened from was recorded."},"intake":{"$ref":"#/components/schemas/CaseIntake"},"handoff":{"$ref":"#/components/schemas/CaseHandoff"}}}}}]},"PatientMessageCreatedEvent":{"allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","properties":{"type":{"type":"string","const":"clinical_case.patient_message_created"},"data":{"type":"object","required":["caseId","messageId","patientId","message","sentAt"],"properties":{"caseId":{"type":"string","format":"uuid"},"messageId":{"type":"string","format":"uuid"},"patientId":{"type":"string","format":"uuid"},"sender":{"type":"string","const":"patient"},"message":{"type":"string"},"sentAt":{"type":"string","format":"date-time"},"replyPath":{"type":"string","description":"`POST`: where to answer, the case's messages path (`/api/v1/clinical-cases/{caseId}/messages`; leave the `/api` off on `https://api.nezercare.com`)."}}}}}]},"ClinicalCaseLifecycleEvent":{"allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","properties":{"type":{"type":"string","enum":["clinical_case.acknowledged","clinical_case.resolved"]},"data":{"type":"object","description":"The same body as `clinical_case.opened` (patient notes, the intake's questions and answers, matched rules, `handoff` and the rest), with the case's status now. It can hold protected health information.","required":["caseId","patientId","status"],"properties":{"caseId":{"type":"string","format":"uuid"},"patientId":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["open","acknowledged","resolved"],"description":"The case's status when the event was built: normally `acknowledged` for `clinical_case.acknowledged` and `resolved` for `clinical_case.resolved`, but a late delivery shows where the case is by then."},"resolutionOutcome":{"type":["string","null"],"description":"Set on `clinical_case.resolved`; null otherwise."},"resolutionNote":{"type":["string","null"],"description":"The team member's note, set on `clinical_case.resolved`; null otherwise."}}}}}]},"PatientDeletedEvent":{"allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","properties":{"type":{"type":"string","const":"patient.deleted"},"data":{"type":"object","required":["patientId","environmentId","deletedAt"],"properties":{"patientId":{"type":"string","format":"uuid"},"environmentId":{"type":"string","format":"uuid"},"reason":{"type":["string","null"],"enum":["patient_request","duplicate_record","entered_in_error","test_record","clinic_policy",null]},"deletedAt":{"type":"string","format":"date-time"}}}}}]},"IntegrationTestEvent":{"allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","properties":{"type":{"type":"string","const":"integration.test"},"data":{"type":"object","required":["test","probeId","environmentId","sentAt","message"],"properties":{"test":{"type":"boolean","const":true},"probeId":{"type":"string","format":"uuid","description":"This test's own ID, the same as the body's `id` and `x-nezer-event-id`."},"environmentId":{"type":"string","format":"uuid"},"sentAt":{"type":"string","format":"date-time"},"message":{"type":"string"}}}}}]},"BillingUsageThresholdReachedEvent":{"allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","properties":{"type":{"type":"string","const":"billing.usage_threshold_reached"},"data":{"oneOf":[{"type":"object","description":"The month's credits.","required":["unit","threshold","creditsUsed","monthlyCredits","remaining","paused"],"properties":{"unit":{"type":"string","const":"credits"},"threshold":{"type":"integer","enum":[80,95,100]},"creditsUsed":{"type":"integer"},"monthlyCredits":{"type":"integer"},"remaining":{"type":"integer","description":"Credits left, top-ups included."},"paused":{"type":"boolean","description":"Whether Nezer's work that uses credits is paused when the event is sent."}}},{"type":"object","description":"An older plan's monthly active-patient limit.","required":["unit","threshold","activePatients","activePatientLimit"],"properties":{"unit":{"type":"string","const":"active_patients"},"threshold":{"type":"integer","enum":[80,100]},"activePatients":{"type":"integer"},"activePatientLimit":{"type":"integer"}}}]}}}]},"SubscriptionUpdatedEvent":{"allOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"object","properties":{"type":{"type":"string","const":"subscription.updated"},"data":{"type":"object","required":["status","plan","reason","recovered","invoicePastDue"],"properties":{"status":{"type":"string","enum":["trialing","active","past_due","grace_period","restricted","canceled","enterprise"]},"plan":{"type":["string","null"],"description":"The plan's code (for example `starter`, `practice`, `growth` or `enterprise`), or null when the change doesn't say."},"reason":{"type":["string","null"],"enum":["PAYMENT_GRACE_PERIOD_EXPIRED",null]},"recovered":{"type":"boolean","description":"True only for a paid invoice that follows a failed payment."},"invoicePastDue":{"type":"boolean","description":"True while an Enterprise invoice is overdue: the plan's own or a credit top-up's."}}}}}]}}}}