API reference
Clinical cases
Report progress, message the patient, resolve.
Confirm processing, report clinical progress, send patient-visible messages, and explicitly resolve escalated cases.
Read current external-care progress
GET/
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.
API key. Authorization: Bearer nzh_prod_… (or a key made earlier, nzh_sb_…): Authentication.
Parameters
| Field | Type | Description |
|---|---|---|
caseIdRequired | path · string (uuid) | The canonical UUID from the clinical_case.opened webhook. This is not the patient-facing NC-XXXXXXXX reference. |
curl "https://api.nezercare.com/v1/clinical-cases/CASE_ID/progress" \
--request GET \
--header "Authorization: Bearer $NEZER_API_KEY"Responses
| Status | Meaning |
|---|---|
200 | Current progress. |
400 | 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. |
401 | MISSING_API_CREDENTIAL: no bearer key was sent. INVALID_API_CREDENTIAL: the key is invalid, expired, or revoked. |
403 | 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. |
404 | No case with this ID in the key's organization. Another organization's case and one that never existed look the same. |
409 | 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. |
429 | 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. |
200 body
| Field | Type | Description |
|---|---|---|
caseIdRequired | string (uuid) | |
statusRequired | string | 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. |
sequenceRequired | integer | The sequence of the latest update; 0 before the first.At least 0. |
nextSequenceRequired | integer | The sequence the next update must use (sequence plus one). After the case is resolved, no update is accepted.At least 1. |
confirmationOverdueRequired | boolean | 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 | string (date-time) or null | 15 minutes after clinical_case.opened was first sent (or the escalation to a Destination was queued); null when neither ever was. |
transportDeliveredRequired | boolean | 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 | string (date-time) or null | 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 | boolean | Whether that appointment has a visit link. The link itself is never returned here: you gave it. |
updatedAt | string (date-time) | |
externalReference | string or null | The externalReference of the latest update. |
{
"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
}{
"message": [
"resolutionNote must be longer than or equal to 10 characters"
],
"error": "Bad Request",
"statusCode": 400
}{
"code": "MISSING_API_CREDENTIAL",
"message": "A bearer API credential is required."
}{
"code": "INVALID_API_CREDENTIAL",
"message": "API credential is invalid."
}{
"code": "BAA_REQUIRED",
"message": "Sign your BAA to turn on patient features. An owner or administrator can sign it in Settings."
}{
"code": "INSUFFICIENT_SCOPE",
"message": "This API key doesn't have the care_handoff scope. Create a key with it in Integrations, API keys."
}{
"message": "Case not found.",
"error": "Not Found",
"statusCode": 404
}{
"message": "Update out of sequence.",
"nextSequence": 2
}{
"message": "This updateId was already used with different content.",
"error": "Conflict",
"statusCode": 409
}{
"message": "The case is already resolved; new updates cannot reopen it.",
"error": "Conflict",
"statusCode": 409
}{
"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."
}{
"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."
}Report provider-workflow progress
POST/
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.
API key. Authorization: Bearer nzh_prod_… (or a key made earlier, nzh_sb_…): Authentication.
Parameters
| Field | Type | Description |
|---|---|---|
caseIdRequired | path · string (uuid) | The canonical UUID from the clinical_case.opened webhook. This is not the patient-facing NC-XXXXXXXX reference. |
Request body
| Field | Type | Description |
|---|---|---|
updateIdRequired | string (uuid) | Generated by you, once for each update. Reuse it only to retry the same update. |
sequenceRequired | integer | Must be exactly nextSequence from the progress endpoint; 409 otherwise.1 to 1000000. |
statusRequired | string | processed only as the first update, and the first update can only be processed.One of processed, scheduled, appointment_cancelled, clinician_responded, patient_contacted, resolved. |
externalReferenceRequired | string | Your own reference for the relevant conversation, appointment, message or case. Not shown to patients; never put a credential in it.1–200 characters. |
scheduledFor | string (date-time) | 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 | string (uri) | 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.Up to 2000 characters.Matches ^https://. |
resolutionOutcome | string | Required for resolved, refused for any other status.One of patient_contacted, provider_follow_up, medication_adjusted, emergency_referral, no_further_action, other. |
resolutionNote | string | Required for resolved, refused for any other status. Kept for the care team's review; not shown to the patient.10–2000 characters. |
curl "https://api.nezercare.com/v1/clinical-cases/CASE_ID/updates" \
--request POST \
--header "Authorization: Bearer $NEZER_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"updateId": "d574b886-f658-43dc-a62a-6c66ef74682d",
"sequence": 1,
"status": "processed",
"externalReference": "provider-conversation-001"
}'{
"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"
}{
"updateId": "3d2c0f0a-6b9e-4b7e-9d8c-5f3a2b1c0e77",
"sequence": 3,
"status": "appointment_cancelled",
"externalReference": "appointment-456"
}{
"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
| Status | Meaning |
|---|---|
200 | Progress recorded or an identical retry recognized. |
400 | 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. |
401 | MISSING_API_CREDENTIAL: no bearer key was sent. INVALID_API_CREDENTIAL: the key is invalid, expired, or revoked. |
403 | 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. |
404 | No case with this ID in the key's organization. Another organization's case and one that never existed look the same. |
409 | 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. |
429 | 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. |
200 body
| Field | Type | Description |
|---|---|---|
caseIdRequired | string (uuid) | |
updateIdRequired | string (uuid) | |
sequenceRequired | integer | |
statusRequired | string | |
duplicateRequired | boolean |
{
"message": [
"resolutionNote must be longer than or equal to 10 characters"
],
"error": "Bad Request",
"statusCode": 400
}{
"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
}{
"code": "VISIT_URL_NOT_ALLOWED",
"message": "The visit link must start with https://.",
"error": "Bad Request",
"statusCode": 400
}{
"code": "MISSING_API_CREDENTIAL",
"message": "A bearer API credential is required."
}{
"code": "INVALID_API_CREDENTIAL",
"message": "API credential is invalid."
}{
"code": "BAA_REQUIRED",
"message": "Sign your BAA to turn on patient features. An owner or administrator can sign it in Settings."
}{
"code": "INSUFFICIENT_SCOPE",
"message": "This API key doesn't have the care_handoff scope. Create a key with it in Integrations, API keys."
}{
"message": "Case not found.",
"error": "Not Found",
"statusCode": 404
}{
"message": "Update out of sequence.",
"nextSequence": 2
}{
"message": "This updateId was already used with different content.",
"error": "Conflict",
"statusCode": 409
}{
"message": "The case is already resolved; new updates cannot reopen it.",
"error": "Conflict",
"statusCode": 409
}{
"code": "NO_APPOINTMENT_TO_CANCEL",
"message": "There is no appointment to cancel.",
"error": "Conflict",
"statusCode": 409
}{
"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."
}{
"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."
}Send a message to the patient
POST/
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.
API key. Authorization: Bearer nzh_prod_… (or a key made earlier, nzh_sb_…): Authentication.
Parameters
| Field | Type | Description |
|---|---|---|
caseIdRequired | path · string (uuid) | The canonical UUID from the clinical_case.opened webhook. This is not the patient-facing NC-XXXXXXXX reference. |
Request body
| Field | Type | Description |
|---|---|---|
messageIdRequired | string (uuid) | |
messageRequired | string | 1–4000 characters. |
externalReferenceRequired | string | 1–200 characters. |
curl "https://api.nezercare.com/v1/clinical-cases/CASE_ID/messages" \
--request POST \
--header "Authorization: Bearer $NEZER_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"messageId": "a321530a-f9fe-4435-8593-38eb75174854",
"message": "A clinician reviewed your concern. Have your symptoms changed today?",
"externalReference": "provider-message-456"
}'Responses
| Status | Meaning |
|---|---|
200 | Message created or an identical retry recognized. |
400 | 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. |
401 | MISSING_API_CREDENTIAL: no bearer key was sent. INVALID_API_CREDENTIAL: the key is invalid, expired, or revoked. |
403 | 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. |
404 | No case with this ID in the key's organization. Another organization's case and one that never existed look the same. |
409 | 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. |
429 | 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. |
200 body
| Field | Type | Description |
|---|---|---|
caseIdRequired | string (uuid) | |
messageIdRequired | string (uuid) | |
duplicateRequired | boolean | |
createdAt | string (date-time) | When the message was stored. Left out of a retry's answer (duplicate: true). |
{
"message": [
"resolutionNote must be longer than or equal to 10 characters"
],
"error": "Bad Request",
"statusCode": 400
}{
"code": "MISSING_API_CREDENTIAL",
"message": "A bearer API credential is required."
}{
"code": "INVALID_API_CREDENTIAL",
"message": "API credential is invalid."
}{
"code": "BAA_REQUIRED",
"message": "Sign your BAA to turn on patient features. An owner or administrator can sign it in Settings."
}{
"code": "INSUFFICIENT_SCOPE",
"message": "This API key doesn't have the care_handoff scope. Create a key with it in Integrations, API keys."
}{
"message": "Case not found.",
"error": "Not Found",
"statusCode": 404
}{
"message": "Update out of sequence.",
"nextSequence": 2
}{
"message": "This updateId was already used with different content.",
"error": "Conflict",
"statusCode": 409
}{
"message": "The case is already resolved; new updates cannot reopen it.",
"error": "Conflict",
"statusCode": 409
}{
"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."
}{
"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."
}