Skip to content

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

  1. Receive clinical_case.opened. Your endpoint gets a signed webhook with the case. Verify the signature and deduplicate by x-nezer-event-id before you act on it. Its source says where it came from; a staff_slack case was raised by your team in Slack, not reported by the patient.
  2. Return processed. Post a case update with status: "processed" at sequence: 1. It's required, and it must be the first update.
  3. Message and update as work happens. Send messages the patient can read, and report scheduling, a clinician's response or contact with the patient.
  4. Resolve explicitly. Close the case with a resolved update, a resolutionOutcome and 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.

data.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."
    }
  ],
  "omittedQuestions": 0
}
  • kind is safety for one of your safety checks and follow_up for an approved question (or the closing “anything else” line). question is the line as the patient read it, in their language (language, en or es).
  • answer is what the patient sent. On a safety check answered with a button, choice is yes, no or unsure in any language, so you need not read it. An answer of null means 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 in omittedQuestions. 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: null and 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
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

StatusWhen to send it
processedFirst, at sequence 1, and only then. The case has landed in your workflow.
scheduledYour 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_cancelledThe appointment was cancelled. Takes no time and no link. It is refused with 409 when the case has no appointment to cancel.
clinician_respondedA clinician has reviewed or responded to the case.
patient_contactedYour team reached the patient outside NezerCare's messages.
resolvedLast. 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
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 (scheduledFor and visitUrl) 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, or null once it is cancelled or the case resolved) and hasVisitLink, 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
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.