Skip to content

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/v1/clinical-cases/{caseId}/progress

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

FieldTypeDescription
caseIdRequiredpath · string (uuid)The canonical UUID from the clinical_case.opened webhook. This is not the patient-facing NC-XXXXXXXX reference.
cURL
curl "https://api.nezercare.com/v1/clinical-cases/CASE_ID/progress" \
  --request GET \
  --header "Authorization: Bearer $NEZER_API_KEY"

Responses

StatusMeaning
200Current progress.
400The 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.
401MISSING_API_CREDENTIAL: no bearer key was sent. INVALID_API_CREDENTIAL: the key is invalid, expired, or revoked.
403BAA_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.
404No case with this ID in the key's organization. Another organization's case and one that never existed look the same.
409A 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.
429RATE_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

FieldTypeDescription
caseIdRequiredstring (uuid)
statusRequiredstringThe 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.
sequenceRequiredintegerThe sequence of the latest update; 0 before the first.At least 0.
nextSequenceRequiredintegerThe sequence the next update must use (sequence plus one). After the case is resolved, no update is accepted.At least 1.
confirmationOverdueRequiredbooleanTrue 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.
confirmationDueAtstring (date-time) or null15 minutes after clinical_case.opened was first sent (or the escalation to a Destination was queued); null when neither ever was.
transportDeliveredRequiredbooleanWhether 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.
scheduledForstring (date-time) or nullThe 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.
hasVisitLinkbooleanWhether that appointment has a visit link. The link itself is never returned here: you gave it.
updatedAtstring (date-time)
externalReferencestring or nullThe externalReference of the latest update.
200 response
{
  "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 response
{
  "message": [
    "resolutionNote must be longer than or equal to 10 characters"
  ],
  "error": "Bad Request",
  "statusCode": 400
}
401: No key sent
{
  "code": "MISSING_API_CREDENTIAL",
  "message": "A bearer API credential is required."
}
401: Invalid, expired or revoked key
{
  "code": "INVALID_API_CREDENTIAL",
  "message": "API credential is invalid."
}
403: BAA not signed
{
  "code": "BAA_REQUIRED",
  "message": "Sign your BAA to turn on patient features. An owner or administrator can sign it in Settings."
}
403: The key lacks the scope
{
  "code": "INSUFFICIENT_SCOPE",
  "message": "This API key doesn't have the care_handoff scope. Create a key with it in Integrations, API keys."
}
404 response
{
  "message": "Case not found.",
  "error": "Not Found",
  "statusCode": 404
}
409: An update out of sequence
{
  "message": "Update out of sequence.",
  "nextSequence": 2
}
409: An ID reused with different content
{
  "message": "This updateId was already used with different content.",
  "error": "Conflict",
  "statusCode": 409
}
409: An update to a resolved case
{
  "message": "The case is already resolved; new updates cannot reopen it.",
  "error": "Conflict",
  "statusCode": 409
}
409: A key of a retired workspace
{
  "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 response
{
  "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/v1/clinical-cases/{caseId}/updates

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

FieldTypeDescription
caseIdRequiredpath · string (uuid)The canonical UUID from the clinical_case.opened webhook. This is not the patient-facing NC-XXXXXXXX reference.

Request body

FieldTypeDescription
updateIdRequiredstring (uuid)Generated by you, once for each update. Reuse it only to retry the same update.
sequenceRequiredintegerMust be exactly nextSequence from the progress endpoint; 409 otherwise.1 to 1000000.
statusRequiredstringprocessed only as the first update, and the first update can only be processed.One of processed, scheduled, appointment_cancelled, clinician_responded, patient_contacted, resolved.
externalReferenceRequiredstringYour own reference for the relevant conversation, appointment, message or case. Not shown to patients; never put a credential in it.1–200 characters.
scheduledForstring (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.
visitUrlstring (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://.
resolutionOutcomestringRequired for resolved, refused for any other status.One of patient_contacted, provider_follow_up, medication_adjusted, emergency_referral, no_further_action, other.
resolutionNotestringRequired for resolved, refused for any other status. Kept for the care team's review; not shown to the patient.10–2000 characters.
cURL
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"
  }'
Appointment scheduled
{
  "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"
}
Appointment cancelled
{
  "updateId": "3d2c0f0a-6b9e-4b7e-9d8c-5f3a2b1c0e77",
  "sequence": 3,
  "status": "appointment_cancelled",
  "externalReference": "appointment-456"
}
Case resolved
{
  "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

StatusMeaning
200Progress recorded or an identical retry recognized.
400The 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.
401MISSING_API_CREDENTIAL: no bearer key was sent. INVALID_API_CREDENTIAL: the key is invalid, expired, or revoked.
403BAA_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.
404No case with this ID in the key's organization. Another organization's case and one that never existed look the same.
409A 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.
429RATE_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

FieldTypeDescription
caseIdRequiredstring (uuid)
updateIdRequiredstring (uuid)
sequenceRequiredinteger
statusRequiredstring
duplicateRequiredboolean
400: A field outside its limits
{
  "message": [
    "resolutionNote must be longer than or equal to 10 characters"
  ],
  "error": "Bad Request",
  "statusCode": 400
}
400: A booking without a visit link
{
  "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
}
400: A link that isn't https
{
  "code": "VISIT_URL_NOT_ALLOWED",
  "message": "The visit link must start with https://.",
  "error": "Bad Request",
  "statusCode": 400
}
401: No key sent
{
  "code": "MISSING_API_CREDENTIAL",
  "message": "A bearer API credential is required."
}
401: Invalid, expired or revoked key
{
  "code": "INVALID_API_CREDENTIAL",
  "message": "API credential is invalid."
}
403: BAA not signed
{
  "code": "BAA_REQUIRED",
  "message": "Sign your BAA to turn on patient features. An owner or administrator can sign it in Settings."
}
403: The key lacks the scope
{
  "code": "INSUFFICIENT_SCOPE",
  "message": "This API key doesn't have the care_handoff scope. Create a key with it in Integrations, API keys."
}
404 response
{
  "message": "Case not found.",
  "error": "Not Found",
  "statusCode": 404
}
409: An update out of sequence
{
  "message": "Update out of sequence.",
  "nextSequence": 2
}
409: An ID reused with different content
{
  "message": "This updateId was already used with different content.",
  "error": "Conflict",
  "statusCode": 409
}
409: An update to a resolved case
{
  "message": "The case is already resolved; new updates cannot reopen it.",
  "error": "Conflict",
  "statusCode": 409
}
409: A cancellation with no appointment to cancel
{
  "code": "NO_APPOINTMENT_TO_CANCEL",
  "message": "There is no appointment to cancel.",
  "error": "Conflict",
  "statusCode": 409
}
409: A key of a retired workspace
{
  "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 response
{
  "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/v1/clinical-cases/{caseId}/messages

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

FieldTypeDescription
caseIdRequiredpath · string (uuid)The canonical UUID from the clinical_case.opened webhook. This is not the patient-facing NC-XXXXXXXX reference.

Request body

FieldTypeDescription
messageIdRequiredstring (uuid)
messageRequiredstring1–4000 characters.
externalReferenceRequiredstring1–200 characters.
cURL
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

StatusMeaning
200Message created or an identical retry recognized.
400The 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.
401MISSING_API_CREDENTIAL: no bearer key was sent. INVALID_API_CREDENTIAL: the key is invalid, expired, or revoked.
403BAA_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.
404No case with this ID in the key's organization. Another organization's case and one that never existed look the same.
409A 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.
429RATE_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

FieldTypeDescription
caseIdRequiredstring (uuid)
messageIdRequiredstring (uuid)
duplicateRequiredboolean
createdAtstring (date-time)When the message was stored. Left out of a retry's answer (duplicate: true).
400 response
{
  "message": [
    "resolutionNote must be longer than or equal to 10 characters"
  ],
  "error": "Bad Request",
  "statusCode": 400
}
401: No key sent
{
  "code": "MISSING_API_CREDENTIAL",
  "message": "A bearer API credential is required."
}
401: Invalid, expired or revoked key
{
  "code": "INVALID_API_CREDENTIAL",
  "message": "API credential is invalid."
}
403: BAA not signed
{
  "code": "BAA_REQUIRED",
  "message": "Sign your BAA to turn on patient features. An owner or administrator can sign it in Settings."
}
403: The key lacks the scope
{
  "code": "INSUFFICIENT_SCOPE",
  "message": "This API key doesn't have the care_handoff scope. Create a key with it in Integrations, API keys."
}
404 response
{
  "message": "Case not found.",
  "error": "Not Found",
  "statusCode": 404
}
409: An update out of sequence
{
  "message": "Update out of sequence.",
  "nextSequence": 2
}
409: An ID reused with different content
{
  "message": "This updateId was already used with different content.",
  "error": "Conflict",
  "statusCode": 409
}
409: An update to a resolved case
{
  "message": "The case is already resolved; new updates cannot reopen it.",
  "error": "Conflict",
  "statusCode": 409
}
409: A key of a retired workspace
{
  "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 response
{
  "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."
}