Guides
Take cases into your clinical system
When a patient reports something that needs a clinician, NezerCare opens a case and sends it to your endpoint. From there it goes into your clinical workflow, whether that's your EHR, your provider network, or your own tools. NezerCare just needs to hear back.
The clinical boundary
A delivered webhook confirms transport only; it never means a clinician reviewed the case. If your system schedules care, report it as a scheduled update, with the link the patient joins the visit with. Only an explicit resolution closes a case: your resolved update, or a team member resolving it in NezerCare.
The handoff
- Receive
clinical_case.opened. Your endpoint gets a signed webhook with the case. Verify the signature and deduplicate byx-nezer-event-idbefore you act on it. Itssourcesays where it came from; astaff_slackcase was raised by your team in Slack, not reported by the patient. - Return
processed. Post a case update withstatus: "processed"atsequence: 1. It's required, and it must be the first update. - Message and update as work happens. Send messages the patient can read, and report scheduling, a clinician's response or contact with the patient.
- Resolve explicitly. Close the case with a
resolvedupdate, aresolutionOutcomeand a note. Nothing else closes a case: not a delivered webhook, an appointment or a clinician's response.
Use the caseId UUID from the webhook in every call. It isn't the NC-XXXXXXXX reference the patient sees. The webhook's data.handoff lists the three paths (progressPath, updatesPath, messagesPath). They are the API's own and start with /api/v1/…: on https://api.nezercare.com leave the /api off. No API key is in the webhook.
The resolution is yours to report, and it is final. If a member of your team resolves the case in NezerCare first, you get a clinical_case.resolved webhook (if your endpoint is subscribed to it) and your later updates are refused with 409. A resolved update from your system sends no webhook back to you.
What the patient answered
Before a concern becomes a case, NezerCare asks the patient your approved follow-up questions and your safety checks. The case carries those questions and the patient's answers, so your system has what your care team sees in the conversation. They are in data.intake of clinical_case.opened, and in intake of the escalation JSON if your system is reached through a Destination. Both carry the same thing, in the order the questions were asked.
{
"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."
}
],
"omittedQuestions": 0
}kindissafetyfor one of your safety checks andfollow_upfor an approved question (or the closing “anything else” line).questionis the line as the patient read it, in their language (language,enores).answeris what the patient sent. On a safety check answered with a button,choiceisyes,noorunsurein any language, so you need not read it. Ananswerofnullmeans the case was sent before the patient answered that question.- An answer over 1,000 characters is cut and ends with
… [truncated]; more than 50 questions are counted inomittedQuestions. The whole reply stays in the case's conversation in NezerCare. - An emergency carries what was asked before it. A case a teammate raised from Slack, and one opened before October 24, 2026, have
language: nulland no questions.
It holds only what the patient saw and answered. It never holds NezerCare's summary or notes, your team's messages, or anything after the case opened, and a retry sends the same intake. It can contain protected health information: keep it out of ordinary logs. The escalation to a Destination is described in the webhook events reference.
Report progress
Every update needs the next consecutive sequence, which the progress endpoint returns as nextSequence. A skipped or reused number is refused with 409, and the error carries the nextSequence to send. Retry an uncertain request with the same updateId and an identical body: the answer is the original, marked duplicate: true. Every update also needs an externalReference (1 to 200 characters): your own reference, never shown to the patient.
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": "b1e6b8a2-2f0e-4a3a-9c1e-2a6b7e9f1a44",
"sequence": 1,
"status": "processed",
"externalReference": "provider-ticket-88213"
}'Statuses
| Status | When to send it |
|---|---|
processed | First, at sequence 1, and only then. The case has landed in your workflow. |
scheduled | Your system booked care for the patient. Needs scheduledFor, a date and time with a time zone, such as 2026-09-08T14:30:00-04:00, and visitUrl, the link the patient joins the visit with. No other status takes either. Report another scheduled update, with its link again, to reschedule. |
appointment_cancelled | The appointment was cancelled. Takes no time and no link. It is refused with 409 when the case has no appointment to cancel. |
clinician_responded | A clinician has reviewed or responded to the case. |
patient_contacted | Your team reached the patient outside NezerCare's messages. |
resolved | Last. Needs a resolutionOutcome (patient_contacted, provider_follow_up, medication_adjusted, emergency_referral, no_further_action or other) and a resolutionNote of 10 to 2,000 characters. No other status takes them. The note is kept for your care team's review, not shown to the patient. |
Every status except processed also queues a short email to the patient: “An appointment was scheduled”, “Your appointment was cancelled”, “Your care team has responded”, “Your care team recorded contact with you” or “Your care request was closed”, with no medical detail, and a secure link when your widget page is set. 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 one). A message and a clinician_responded update sent together are one “Your care team has responded”, not two. Appointment reminders are separate emails. A clinic that runs its own patient portal and chose Your portal only for who tells the patient isn't emailed for that portal's cases (see What patients are emailed).
A case that has had no update 15 minutes after its clinical_case.opened was first sent shows as overdue in the progress (confirmationOverdue) and to your team in NezerCare. It's a reminder to follow up, not a promise about how fast a clinician responds.
Appointments, visit links and reminders
A visit link is now required to book
October 2026: a scheduled update without visitUrl is refused with 400 and code: "VISIT_URL_REQUIRED". It used to be accepted. Retrying an update you sent before the change, unchanged, still answers 200 with duplicate: true. Appointments already booked keep working; the patient sees their time and no Join visit button.
visitUrl must be an https:// address of a real website: no http:, no username or password, not localhost, an IP address or a private name such as .internal, no spaces, at most 2,000 characters. A link that breaks a rule gets 400 with a code (VISIT_URL_REQUIRED, VISIT_URL_INVALID or VISIT_URL_NOT_ALLOWED) and a message that says what to fix. The link lets whoever has it join the visit, so NezerCare stores it encrypted and never writes it to a log, an audit event or an email.
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": "f1cbf8d0-6827-47d4-b48b-d82cd9e4d754",
"sequence": 2,
"status": "scheduled",
"externalReference": "appointment-456",
"scheduledFor": "2026-09-08T14:30:00-04:00",
"visitUrl": "https://visit.example-clinic.com/rooms/456"
}'- The patient sees the time in their own time zone and a Join visit button in the widget, from booking until an hour after the start (not once the case is closed or the appointment cancelled). Emails never carry the link.
- Your own portal gets
appointment(scheduledForandvisitUrl) on the patient's conversation; the webhook says the appointment changed but never carries the link. - Reminders: the patient is emailed a day and an hour before, with a secure link back to the widget. A reminder whose time has already passed when you book is skipped. Rescheduling replaces them; cancelling the appointment or resolving the case stops them. They follow the rules of every patient email (held until the BAA is signed, never sent twice, not sent under Your portal only).
- Clinicians: an appointment your system books sends no email to your staff. Your own system looks after its own clinicians. (A staff member who books in NezerCare is reminded an hour before.)
- Progress reports
scheduledFor(your appointment, ornullonce it is cancelled or the case resolved) andhasVisitLink, never the link.
Message the patient
Messages appear in the patient's secure case conversation in the widget, or in the conversation of your own patient portal. The patient gets an email saying there's a new message, never the message itself (not for a portal clinic that chose Your portal only). A message is 1 to 4,000 characters, with its own messageId and externalReference. You can still send one after the case is resolved, but a portal conversation that has already closed doesn't take it into its feed.
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": "0b8f1a3e-6c2d-4f9a-8e51-1d9b6c4a7f02",
"message": "Your care team has your update and will follow up shortly.",
"externalReference": "provider-ticket-88213"
}'The patient reads this field
Keep internal clinical notes in your own system and send only what the patient should read. When the patient replies, you get a clinical_case.patient_message_created webhook.