Skip to content

API reference

Patient messaging

Identify patients and exchange their messages from your own portal.

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.

Add a photo or PDF

POST/v1/patients/{patientId}/conversations/{conversationId}/attachments

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.

API key. Authorization: Bearer nzh_prod_… (or a key made earlier, nzh_sb_…): Authentication.

Parameters

FieldTypeDescription
patientIdRequiredpath · string (uuid)The patient's NezerCare ID, from POST /v1/patients/identify. Another workspace's patient, or one that isn't this conversation's, is 404.
conversationIdRequiredpath · string (uuid)The conversation's ID, from the response that started it.

Responses

StatusMeaning
200A file with these bytes was already added: this is it.
201The file was added.
400INVALID_REQUEST: no file in the field file, a file in another field, more than one file, or any other form field.
401The API key is missing, invalid, expired or turned off.
403BAA_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.
404PATIENT_NOT_FOUND or CONVERSATION_NOT_FOUND.
409ATTACHMENT_NOT_EXPECTED (nowhere to attach a file right now), ATTACHMENT_LIMIT_REACHED (10 files already), CONVERSATION_CLOSED or PATIENT_INACTIVE.
413ATTACHMENT_TOO_LARGE: over 10 MB.
415ATTACHMENT_TYPE_NOT_ALLOWED: not a JPEG, PNG, WebP, HEIC or PDF.
422ATTACHMENT_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.
429RATE_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.
503PATIENT_FILES_UNAVAILABLE: storage is temporarily unavailable. No attachment was stored; wait for Retry-After and retry.

200 body

FieldTypeDescription
idRequiredstring (uuid)List it in the patient's next message.
fileNameRequiredstringThe name cleaned of any path, with the real extension.
contentTypeRequiredstringFrom the file's first bytes.One of image/jpeg, image/png, image/webp, image/heic, application/pdf.
sizeBytesRequiredintegerOf the file as stored, after cleaning.
sha256RequiredstringOf 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.
200 response
{
  "id": "a0b1c2d3-e4f5-4a6b-8c7d-9e0f1a2b3c4d",
  "fileName": "spot.jpg",
  "contentType": "image/jpeg",
  "sizeBytes": 482113,
  "sha256": "3c9a1f5b7d2e4a6c8b0d1e3f5a7c9b2d4e6f8a0b1c3d5e7f9a1b3c5d7e9f0a2b"
}

201 body

FieldTypeDescription
idRequiredstring (uuid)List it in the patient's next message.
fileNameRequiredstringThe name cleaned of any path, with the real extension.
contentTypeRequiredstringFrom the file's first bytes.One of image/jpeg, image/png, image/webp, image/heic, application/pdf.
sizeBytesRequiredintegerOf the file as stored, after cleaning.
sha256RequiredstringOf 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.
201 response
{
  "id": "a0b1c2d3-e4f5-4a6b-8c7d-9e0f1a2b3c4d",
  "fileName": "spot.jpg",
  "contentType": "image/jpeg",
  "sizeBytes": 482113,
  "sha256": "3c9a1f5b7d2e4a6c8b0d1e3f5a7c9b2d4e6f8a0b1c3d5e7f9a1b3c5d7e9f0a2b"
}
400 response
{
  "code": "INVALID_REQUEST",
  "message": "Send only the file, in the form field \"file\", with no other form fields."
}
401 response
{
  "code": "INVALID_API_CREDENTIAL",
  "message": "API credential is invalid."
}
403 response
{
  "code": "INSUFFICIENT_SCOPE",
  "message": "This API key doesn't have the portal_messaging scope. Create a key with it in Integrations, API keys."
}
404 response
{
  "code": "CONVERSATION_NOT_FOUND",
  "message": "No conversation with this ID for this patient."
}
409 response
{
  "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 response
{
  "code": "ATTACHMENT_TOO_LARGE",
  "message": "Files can be up to 10 MB."
}
415 response
{
  "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 response
{
  "code": "ATTACHMENT_REJECTED",
  "message": "We couldn't accept this file. Please try a different photo or PDF."
}
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."
}
503 response
{
  "code": "PATIENT_FILES_UNAVAILABLE",
  "message": "File storage is temporarily unavailable. Retry the upload."
}

Identify a patient

POST/v1/patients/identify

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.

API key. Authorization: Bearer nzh_prod_… (or a key made earlier, nzh_sb_…): Authentication.

Request body

FieldTypeDescription
externalPatientIdRequiredstringYour permanent ID for the patient. The same ID reaches the same patient from the widget.1–200 characters.
givenNamestringRequired the first time (1 to 80 characters).Up to 80 characters.
familyNamestringUp to 80 characters.
emailstring (email)Required the first time.Up to 254 characters.
phonestring7–30 characters.
cURL
curl "https://api.nezercare.com/v1/patients/identify" \
  --request POST \
  --header "Authorization: Bearer $NEZER_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "externalPatientId": "pt_48213",
    "givenName": "Maria",
    "familyName": "Lopez",
    "email": "maria@example.com",
    "phone": "+15555550100"
  }'

Responses

StatusMeaning
200A patient NezerCare already knew.
201A patient added.
400PATIENT_PROFILE_REQUIRED: NezerCare doesn't know this patient yet and no valid givenName and email were sent. Or INVALID_REQUEST.
401The API key is missing, invalid, expired or turned off.
403BAA_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.
404PATIENT_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.
409PATIENT_INACTIVE: this patient's care has been cancelled. Or PATIENT_ID_UNAVAILABLE (the ID can't be used here) or ENVIRONMENT_RETIRED.
429PATIENT_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.

200 body

FieldTypeDescription
patientIdRequiredstring (uuid)Keep it: every other call names it in the path.
externalPatientIdRequiredstring
createdRequiredbooleanWhether this call added the patient.
statusRequiredstringOne of active.
200 response
{
  "patientId": "2c3d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f",
  "externalPatientId": "pt_48213",
  "created": false,
  "status": "active"
}

201 body

FieldTypeDescription
patientIdRequiredstring (uuid)Keep it: every other call names it in the path.
externalPatientIdRequiredstring
createdRequiredbooleanWhether this call added the patient.
statusRequiredstringOne of active.
201 response
{
  "patientId": "2c3d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f",
  "externalPatientId": "pt_48213",
  "created": true,
  "status": "active"
}
400 response
{
  "code": "PATIENT_PROFILE_REQUIRED",
  "message": "NezerCare doesn't know this patient yet. Send their givenName and email to add them."
}
401 response
{
  "code": "INVALID_API_CREDENTIAL",
  "message": "API credential is invalid."
}
403 response
{
  "code": "INSUFFICIENT_SCOPE",
  "message": "This API key doesn't have the portal_messaging scope. Create a key with it in Integrations, API keys."
}
404 response
{
  "code": "PATIENT_NOT_FOUND",
  "message": "No patient with this ID in this workspace."
}
409 response
{
  "code": "PATIENT_INACTIVE",
  "message": "This patient's care has been cancelled."
}
429 response
{
  "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."
}

List the patient's conversations

GET/v1/patients/{patientId}/conversations

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.

A 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.

API key. Authorization: Bearer nzh_prod_… (or a key made earlier, nzh_sb_…): Authentication.

Parameters

FieldTypeDescription
patientIdRequiredpath · string (uuid)The patient's NezerCare ID, from POST /v1/patients/identify. Another workspace's patient, or one that isn't this conversation's, is 404.
statusquery · stringOnly open, or only closed, conversations.One of open, closed.
limitquery · integerAt most this many conversations (up to 50).1 to 50.Defaults to 20.
afterquery · stringThe nextCursor of the previous page.Up to 400 characters.
cURL
curl "https://api.nezercare.com/v1/patients/PATIENT_ID/conversations?limit=20" \
  --request GET \
  --header "Authorization: Bearer $NEZER_API_KEY"

Responses

StatusMeaning
200A page of the patient's conversations.
400INVALID_REQUEST: a limit out of range, an unknown status, or an after that isn't a cursor this API returned.
401The API key is missing, invalid, expired or turned off.
403BAA_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.
404PATIENT_NOT_FOUND: no such patient in this workspace (another workspace's patient, or a real patient to a nzh_test_ key).
429RATE_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.

200 body

FieldTypeDescription
conversationsRequiredarray of objectsNewest activity first.
conversations[].idRequiredstring (uuid)
conversations[].patientIdRequiredstring (uuid)
conversations[].externalConversationIdstring or null
conversations[].channelRequiredstringOne of portal_api.
conversations[].statusRequiredstringOne of open, closed.
conversations[].careStatusRequiredobjectWhere the conversation stands, in the widget's own words only.
conversations[].careStatus.codeRequiredstringOne of received, in_progress, replied, scheduled, closed.
conversations[].careStatus.labelRequiredstringExample: New reply from your care team.
conversations[].appointmentRequiredobjectThe 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.
conversations[].showCall911RequiredbooleanTrue while an emergency conversation is open: keep the 911 guidance in view.
conversations[].awaitingRequiredobjectA hint for the composer, never a lock: free text is always accepted.
conversations[].awaiting.typeRequiredstringWhat the latest message from NezerCare waits for: one of its buttons, words (with choices as shortcuts, if any), or photos (then done or skip).One of none, choice, text, attachments.
conversations[].awaiting.messageIdstring (uuid)
conversations[].awaiting.choicesarray of strings
conversations[].lastSequenceRequiredintegerAt least 0.
conversations[].versionRequiredintegerIncreases whenever the conversation changes.At least 1.
conversations[].languageRequiredstringOne of en, es.
conversations[].safetyRequiredobjectThe 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.
conversations[].safety.languageRequiredstringOne of en, es.
conversations[].safety.emergencyLineRequiredstringExample: If this is a medical emergency, call 911..
conversations[].safety.linesRequiredarray of objects
conversations[].safety.lines[].labelRequiredstringExample: Call 911.
conversations[].safety.lines[].telRequiredstringExample: tel:911.
conversations[].createdAtRequiredstring (date-time)
conversations[].updatedAtRequiredstring (date-time)
hasMoreRequiredbooleanTrue when another page follows.
nextCursorRequiredstring or nullPass it as after for the next page. Opaque: never build one.
FieldTypeDescription
scheduledForRequiredstring (date-time)The start, in UTC (show it in the patient's own time zone).
visitUrlstring (uri) or nullThe link to join the visit; null for an appointment booked before links were required; absent in a webhook.
200 response
{
  "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 response
{
  "code": "INVALID_REQUEST",
  "message": "after isn't a cursor this API returned. Use the nextCursor of the previous page."
}
401 response
{
  "code": "INVALID_API_CREDENTIAL",
  "message": "API credential is invalid."
}
403 response
{
  "code": "INSUFFICIENT_SCOPE",
  "message": "This API key doesn't have the portal_messaging scope. Create a key with it in Integrations, API keys."
}
404 response
{
  "code": "PATIENT_NOT_FOUND",
  "message": "No patient with this ID in this workspace."
}
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."
}

Start a conversation

POST/v1/patients/{patientId}/conversations

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.

Returns 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).

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.

If 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.

Otherwise the message is handled like the widget handles it:

- 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. - A billing, scheduling, fulfillment or support request starts a short guided chat the same way (question, review, handoff). - 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). - An everyday business question is answered from the clinic's own knowledge with its sources (kind: "answer", one credit). - A message in a conversation the team already has goes into that thread, with no reply from NezerCare.

If 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.

Each 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.

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.

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.

Send 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.

API key. Authorization: Bearer nzh_prod_… (or a key made earlier, nzh_sb_…): Authentication.

Parameters

FieldTypeDescription
patientIdRequiredpath · string (uuid)The patient's NezerCare ID, from POST /v1/patients/identify. Another workspace's patient, or one that isn't this conversation's, is 404.

Request body

FieldTypeDescription
requestIdRequiredstring (uuid)Generate one per message. The same one again returns the same conversation and the same replies.
externalConversationIdstringYour own ID for the conversation, unique in the workspace, so you can map it without storing ours.1–200 characters.
languagestringThe portal's screen language. The reply follows the message's own language when it is clearly English or Spanish.One of en, es.
textRequiredstringThe patient's words, exactly as typed: don't filter, hold or edit them first.1–10000 characters.
cURL
curl "https://api.nezercare.com/v1/patients/PATIENT_ID/conversations" \
  --request POST \
  --header "Authorization: Bearer $NEZER_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "requestId": "9d1f7a52-3c6e-4b85-8f0a-5b2c1d7e9a30",
    "externalConversationId": "portal-thread-991",
    "language": "en",
    "text": "Do you ship to Texas?"
  }'

Responses

StatusMeaning
201The conversation, the patient's message and NezerCare's replies.
400INVALID_REQUEST: a malformed body, or text over 10,000 characters.
401The API key is missing, invalid, expired or turned off.
403BAA_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.
404PATIENT_NOT_FOUND: no such patient in this workspace.
409REQUEST_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).
429RATE_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.
500A 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.

201 body

FieldTypeDescription
conversationRequiredobject
conversation.idRequiredstring (uuid)
conversation.patientIdRequiredstring (uuid)
conversation.externalConversationIdstring or null
conversation.channelRequiredstringOne of portal_api.
conversation.statusRequiredstringOne of open, closed.
conversation.careStatusRequiredobjectWhere the conversation stands, in the widget's own words only.
conversation.careStatus.codeRequiredstringOne of received, in_progress, replied, scheduled, closed.
conversation.careStatus.labelRequiredstringExample: New reply from your care team.
conversation.appointmentRequiredobjectThe 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.
conversation.showCall911RequiredbooleanTrue while an emergency conversation is open: keep the 911 guidance in view.
conversation.awaitingRequiredobjectA hint for the composer, never a lock: free text is always accepted.
conversation.awaiting.typeRequiredstringWhat the latest message from NezerCare waits for: one of its buttons, words (with choices as shortcuts, if any), or photos (then done or skip).One of none, choice, text, attachments.
conversation.awaiting.messageIdstring (uuid)
conversation.awaiting.choicesarray of strings
conversation.lastSequenceRequiredintegerAt least 0.
conversation.versionRequiredintegerIncreases whenever the conversation changes.At least 1.
conversation.languageRequiredstringOne of en, es.
conversation.safetyRequiredobjectThe 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.
conversation.safety.languageRequiredstringOne of en, es.
conversation.safety.emergencyLineRequiredstringExample: If this is a medical emergency, call 911..
conversation.safety.linesRequiredarray of objects
conversation.safety.lines[].labelRequiredstringExample: Call 911.
conversation.safety.lines[].telRequiredstringExample: tel:911.
conversation.createdAtRequiredstring (date-time)
conversation.updatedAtRequiredstring (date-time)
messageRequiredobjectOne message of a conversation. text is always the words to show; the rest depends on kind.
repliesRequiredarray of objectsNezerCare'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.
showCall911RequiredbooleanTrue when the message was an emergency.
emergencyRequiredobject
duplicateRequiredbooleanTrue 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).
FieldTypeDescription
scheduledForRequiredstring (date-time)The start, in UTC (show it in the patient's own time zone).
visitUrlstring (uri) or nullThe link to join the visit; null for an appointment booked before links were required; absent in a webhook.
FieldTypeDescription
idRequiredstring (uuid)For the patient's own message, the requestId they sent.
sequenceRequiredintegerPosition in the conversation: 1, 2, 3 with no gaps. Order by this.At least 1.
kindRequiredstringOne of text, answer, question, review, emergency, handoff, notice, orders, closed.
fromRequiredobject
from.kindRequiredstringnezer 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.One of patient, nezer, care_team, system.
from.labelRequiredstringThe words to show: "You", "NezerCare", "Care team" (Spanish "Usted", "NezerCare", "Equipo médico"). Staff names are never sent.
priorityRequiredstringOne of normal, emergency.
languageRequiredstringThe language of text.One of en, es.
textRequiredstringAlways present: the words to show. A portal that renders nothing else can print text and stay correct. Never rewrite it.
causedByRequestIdstring (uuid)The patient request this message answers, when it answers one.
attachmentsarray of objectsOn a patient's message: the files they listed with it, as metadata (never the contents).
attachments[].idRequiredstring (uuid)
attachments[].fileNameRequiredstring
attachments[].contentTypeRequiredstringOne of image/jpeg, image/png, image/webp, image/heic, application/pdf.
attachments[].sizeBytesRequiredinteger
createdAtRequiredstring (date-time)
FieldTypeDescription
idRequiredstring (uuid)For the patient's own message, the requestId they sent.
sequenceRequiredintegerPosition in the conversation: 1, 2, 3 with no gaps. Order by this.At least 1.
kindRequiredstringOne of text, answer, question, review, emergency, handoff, notice, orders, closed.
fromRequiredobject
from.kindRequiredstringnezer 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.One of patient, nezer, care_team, system.
from.labelRequiredstringThe words to show: "You", "NezerCare", "Care team" (Spanish "Usted", "NezerCare", "Equipo médico"). Staff names are never sent.
priorityRequiredstringOne of normal, emergency.
languageRequiredstringThe language of text.One of en, es.
textRequiredstringAlways present: the words to show. A portal that renders nothing else can print text and stay correct. Never rewrite it.
causedByRequestIdstring (uuid)The patient request this message answers, when it answers one.
attachmentsarray of objectsOn a patient's message: the files they listed with it, as metadata (never the contents).
attachments[].idRequiredstring (uuid)
attachments[].fileNameRequiredstring
attachments[].contentTypeRequiredstringOne of image/jpeg, image/png, image/webp, image/heic, application/pdf.
attachments[].sizeBytesRequiredinteger
createdAtRequiredstring (date-time)
answerIdRequiredstring (uuid)
sourcesRequiredarray of objectsWhere the answer came from. Show them.
sources[].titleRequiredstring
sources[].urlRequiredstring (uri) or null
actionsRequiredarray of objectsAt most a Book button, with an https address on the clinic's site. Never a contact button for a signed-in patient.
actions[].kindRequiredstringOne of book.
actions[].urlRequiredstring (uri)
actions[].labelstringOne of demo, appointment, consultation, call.
choicesRequiredarray of objectsThe buttons under the answer: send the id as choiceId.
choices[].idRequiredstringOne of helpful, talk_to_team.
choices[].labelRequiredstring
FieldTypeDescription
idRequiredstring (uuid)For the patient's own message, the requestId they sent.
sequenceRequiredintegerPosition in the conversation: 1, 2, 3 with no gaps. Order by this.At least 1.
kindRequiredstringOne of text, answer, question, review, emergency, handoff, notice, orders, closed.
fromRequiredobject
from.kindRequiredstringnezer 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.One of patient, nezer, care_team, system.
from.labelRequiredstringThe words to show: "You", "NezerCare", "Care team" (Spanish "Usted", "NezerCare", "Equipo médico"). Staff names are never sent.
priorityRequiredstringOne of normal, emergency.
languageRequiredstringThe language of text.One of en, es.
textRequiredstringAlways present: the words to show. A portal that renders nothing else can print text and stay correct. Never rewrite it.
causedByRequestIdstring (uuid)The patient request this message answers, when it answers one.
attachmentsarray of objectsOn a patient's message: the files they listed with it, as metadata (never the contents).
attachments[].idRequiredstring (uuid)
attachments[].fileNameRequiredstring
attachments[].contentTypeRequiredstringOne of image/jpeg, image/png, image/webp, image/heic, application/pdf.
attachments[].sizeBytesRequiredinteger
createdAtRequiredstring (date-time)
purposeRequiredstringOne of safety_check, intake, team_chat, workflow.
inputRequiredobjectchoice: pick one of choices. text: answer in words (up to maxLength). attachments: add photos with the attachments call, then press done (or skip).
input.typeRequiredstringOne of choice, text, attachments.
input.maxLengthintegerExample: 2000.
input.choicesarray of objects
input.choices[].idRequiredstringSend it as choiceId.One of helpful, talk_to_team, yes, no, unsure, send, send_now, done, skip.
input.choices[].labelRequiredstringThe words on the button, in the message's language.
choicesarray of objectsShortcuts beside the question: send_now ("Send to my care team now", for an urgent concern, at any point) or done and skip for photos.
choices[].idRequiredstringSend it as choiceId.One of helpful, talk_to_team, yes, no, unsure, send, send_now, done, skip.
choices[].labelRequiredstringThe words on the button, in the message's language.
FieldTypeDescription
idRequiredstring (uuid)For the patient's own message, the requestId they sent.
sequenceRequiredintegerPosition in the conversation: 1, 2, 3 with no gaps. Order by this.At least 1.
kindRequiredstringOne of text, answer, question, review, emergency, handoff, notice, orders, closed.
fromRequiredobject
from.kindRequiredstringnezer 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.One of patient, nezer, care_team, system.
from.labelRequiredstringThe words to show: "You", "NezerCare", "Care team" (Spanish "Usted", "NezerCare", "Equipo médico"). Staff names are never sent.
priorityRequiredstringOne of normal, emergency.
languageRequiredstringThe language of text.One of en, es.
textRequiredstringAlways present: the words to show. A portal that renders nothing else can print text and stay correct. Never rewrite it.
causedByRequestIdstring (uuid)The patient request this message answers, when it answers one.
attachmentsarray of objectsOn a patient's message: the files they listed with it, as metadata (never the contents).
attachments[].idRequiredstring (uuid)
attachments[].fileNameRequiredstring
attachments[].contentTypeRequiredstringOne of image/jpeg, image/png, image/webp, image/heic, application/pdf.
attachments[].sizeBytesRequiredinteger
createdAtRequiredstring (date-time)
statusRequiredstringOne of ready, urgent.
summaryRequiredstring
choicesRequiredarray of objects
choices[].idRequiredstringSend it as choiceId.One of helpful, talk_to_team, yes, no, unsure, send, send_now, done, skip.
choices[].labelRequiredstringThe words on the button, in the message's language.
inputRequiredobject
input.typestringOne of text.
input.maxLengthinteger
input.hintstringExample: Need to change something?.
FieldTypeDescription
idRequiredstring (uuid)For the patient's own message, the requestId they sent.
sequenceRequiredintegerPosition in the conversation: 1, 2, 3 with no gaps. Order by this.At least 1.
kindRequiredstringOne of text, answer, question, review, emergency, handoff, notice, orders, closed.
fromRequiredobject
from.kindRequiredstringnezer 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.One of patient, nezer, care_team, system.
from.labelRequiredstringThe words to show: "You", "NezerCare", "Care team" (Spanish "Usted", "NezerCare", "Equipo médico"). Staff names are never sent.
priorityRequiredstringOne of normal, emergency.
languageRequiredstringThe language of text.One of en, es.
textRequiredstringAlways present: the words to show. A portal that renders nothing else can print text and stay correct. Never rewrite it.
causedByRequestIdstring (uuid)The patient request this message answers, when it answers one.
attachmentsarray of objectsOn a patient's message: the files they listed with it, as metadata (never the contents).
attachments[].idRequiredstring (uuid)
attachments[].fileNameRequiredstring
attachments[].contentTypeRequiredstringOne of image/jpeg, image/png, image/webp, image/heic, application/pdf.
attachments[].sizeBytesRequiredinteger
createdAtRequiredstring (date-time)
ordersRequiredarray of objects
orders[].idRequiredstring
orders[].statusRequiredstringOne of processing, shipped, delivered, delayed, cancelled.
orders[].statusLabelstring or null
orders[].carrierstring or null
orders[].trackingUrlstring (uri) or null
orders[].estimatedDeliverystring or null
orders[].placedAtstring or null
orders[].itemsRequiredarray of objects
orders[].items[].nameRequiredstring
orders[].items[].quantityRequiredinteger
FieldTypeDescription
idRequiredstring (uuid)For the patient's own message, the requestId they sent.
sequenceRequiredintegerPosition in the conversation: 1, 2, 3 with no gaps. Order by this.At least 1.
kindRequiredstringOne of text, answer, question, review, emergency, handoff, notice, orders, closed.
fromRequiredobject
from.kindRequiredstringnezer 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.One of patient, nezer, care_team, system.
from.labelRequiredstringThe words to show: "You", "NezerCare", "Care team" (Spanish "Usted", "NezerCare", "Equipo médico"). Staff names are never sent.
priorityRequiredstringOne of normal, emergency.
languageRequiredstringThe language of text.One of en, es.
textRequiredstringAlways present: the words to show. A portal that renders nothing else can print text and stay correct. Never rewrite it.
causedByRequestIdstring (uuid)The patient request this message answers, when it answers one.
attachmentsarray of objectsOn a patient's message: the files they listed with it, as metadata (never the contents).
attachments[].idRequiredstring (uuid)
attachments[].fileNameRequiredstring
attachments[].contentTypeRequiredstringOne of image/jpeg, image/png, image/webp, image/heic, application/pdf.
attachments[].sizeBytesRequiredinteger
createdAtRequiredstring (date-time)
emergencyRequiredobject
emergency.linesRequiredarray of objectsThe ways to call. Thoughts of self-harm add 988.
emergency.lines[].labelRequiredstringExample: Call 911.
emergency.lines[].telRequiredstringExample: tel:911.
emergency.sentToCareTeamRequiredbooleanWhether 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.
FieldTypeDescription
idRequiredstring (uuid)For the patient's own message, the requestId they sent.
sequenceRequiredintegerPosition in the conversation: 1, 2, 3 with no gaps. Order by this.At least 1.
kindRequiredstringOne of text, answer, question, review, emergency, handoff, notice, orders, closed.
fromRequiredobject
from.kindRequiredstringnezer 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.One of patient, nezer, care_team, system.
from.labelRequiredstringThe words to show: "You", "NezerCare", "Care team" (Spanish "Usted", "NezerCare", "Equipo médico"). Staff names are never sent.
priorityRequiredstringOne of normal, emergency.
languageRequiredstringThe language of text.One of en, es.
textRequiredstringAlways present: the words to show. A portal that renders nothing else can print text and stay correct. Never rewrite it.
causedByRequestIdstring (uuid)The patient request this message answers, when it answers one.
attachmentsarray of objectsOn a patient's message: the files they listed with it, as metadata (never the contents).
attachments[].idRequiredstring (uuid)
attachments[].fileNameRequiredstring
attachments[].contentTypeRequiredstringOne of image/jpeg, image/png, image/webp, image/heic, application/pdf.
attachments[].sizeBytesRequiredinteger
createdAtRequiredstring (date-time)
handoffRequiredobject
handoff.referenceRequiredstringSomething the patient and the team can both quote.Matches ^NC-[0-9A-F]{8}$.
handoff.teamRequiredstringOne of clinical, billing, scheduling, fulfillment, support.
handoff.urgencyRequiredstringOne of routine, urgent.
FieldTypeDescription
idRequiredstring (uuid)For the patient's own message, the requestId they sent.
sequenceRequiredintegerPosition in the conversation: 1, 2, 3 with no gaps. Order by this.At least 1.
kindRequiredstringOne of text, answer, question, review, emergency, handoff, notice, orders, closed.
fromRequiredobject
from.kindRequiredstringnezer 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.One of patient, nezer, care_team, system.
from.labelRequiredstringThe words to show: "You", "NezerCare", "Care team" (Spanish "Usted", "NezerCare", "Equipo médico"). Staff names are never sent.
priorityRequiredstringOne of normal, emergency.
languageRequiredstringThe language of text.One of en, es.
textRequiredstringAlways present: the words to show. A portal that renders nothing else can print text and stay correct. Never rewrite it.
causedByRequestIdstring (uuid)The patient request this message answers, when it answers one.
attachmentsarray of objectsOn a patient's message: the files they listed with it, as metadata (never the contents).
attachments[].idRequiredstring (uuid)
attachments[].fileNameRequiredstring
attachments[].contentTypeRequiredstringOne of image/jpeg, image/png, image/webp, image/heic, application/pdf.
attachments[].sizeBytesRequiredinteger
createdAtRequiredstring (date-time)
noticeRequiredobject
notice.codeRequiredstringOne of paused.
FieldTypeDescription
idRequiredstring (uuid)For the patient's own message, the requestId they sent.
sequenceRequiredintegerPosition in the conversation: 1, 2, 3 with no gaps. Order by this.At least 1.
kindRequiredstringOne of text, answer, question, review, emergency, handoff, notice, orders, closed.
fromRequiredobject
from.kindRequiredstringnezer 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.One of patient, nezer, care_team, system.
from.labelRequiredstringThe words to show: "You", "NezerCare", "Care team" (Spanish "Usted", "NezerCare", "Equipo médico"). Staff names are never sent.
priorityRequiredstringOne of normal, emergency.
languageRequiredstringThe language of text.One of en, es.
textRequiredstringAlways present: the words to show. A portal that renders nothing else can print text and stay correct. Never rewrite it.
causedByRequestIdstring (uuid)The patient request this message answers, when it answers one.
attachmentsarray of objectsOn a patient's message: the files they listed with it, as metadata (never the contents).
attachments[].idRequiredstring (uuid)
attachments[].fileNameRequiredstring
attachments[].contentTypeRequiredstringOne of image/jpeg, image/png, image/webp, image/heic, application/pdf.
attachments[].sizeBytesRequiredinteger
createdAtRequiredstring (date-time)
closedRequiredobject
closed.reasonRequiredstringOne of closed.

replies[] with type undefined

FieldTypeDescription
idRequiredstring (uuid)For the patient's own message, the requestId they sent.
sequenceRequiredintegerPosition in the conversation: 1, 2, 3 with no gaps. Order by this.At least 1.
kindRequiredstringOne of text, answer, question, review, emergency, handoff, notice, orders, closed.
fromRequiredobject
from.kindRequiredstringnezer 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.One of patient, nezer, care_team, system.
from.labelRequiredstringThe words to show: "You", "NezerCare", "Care team" (Spanish "Usted", "NezerCare", "Equipo médico"). Staff names are never sent.
priorityRequiredstringOne of normal, emergency.
languageRequiredstringThe language of text.One of en, es.
textRequiredstringAlways present: the words to show. A portal that renders nothing else can print text and stay correct. Never rewrite it.
causedByRequestIdstring (uuid)The patient request this message answers, when it answers one.
attachmentsarray of objectsOn a patient's message: the files they listed with it, as metadata (never the contents).
attachments[].idRequiredstring (uuid)
attachments[].fileNameRequiredstring
attachments[].contentTypeRequiredstringOne of image/jpeg, image/png, image/webp, image/heic, application/pdf.
attachments[].sizeBytesRequiredinteger
createdAtRequiredstring (date-time)

replies[] with type undefined

FieldTypeDescription
idRequiredstring (uuid)For the patient's own message, the requestId they sent.
sequenceRequiredintegerPosition in the conversation: 1, 2, 3 with no gaps. Order by this.At least 1.
kindRequiredstringOne of text, answer, question, review, emergency, handoff, notice, orders, closed.
fromRequiredobject
from.kindRequiredstringnezer 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.One of patient, nezer, care_team, system.
from.labelRequiredstringThe words to show: "You", "NezerCare", "Care team" (Spanish "Usted", "NezerCare", "Equipo médico"). Staff names are never sent.
priorityRequiredstringOne of normal, emergency.
languageRequiredstringThe language of text.One of en, es.
textRequiredstringAlways present: the words to show. A portal that renders nothing else can print text and stay correct. Never rewrite it.
causedByRequestIdstring (uuid)The patient request this message answers, when it answers one.
attachmentsarray of objectsOn a patient's message: the files they listed with it, as metadata (never the contents).
attachments[].idRequiredstring (uuid)
attachments[].fileNameRequiredstring
attachments[].contentTypeRequiredstringOne of image/jpeg, image/png, image/webp, image/heic, application/pdf.
attachments[].sizeBytesRequiredinteger
createdAtRequiredstring (date-time)
answerIdRequiredstring (uuid)
sourcesRequiredarray of objectsWhere the answer came from. Show them.
sources[].titleRequiredstring
sources[].urlRequiredstring (uri) or null
actionsRequiredarray of objectsAt most a Book button, with an https address on the clinic's site. Never a contact button for a signed-in patient.
actions[].kindRequiredstringOne of book.
actions[].urlRequiredstring (uri)
actions[].labelstringOne of demo, appointment, consultation, call.
choicesRequiredarray of objectsThe buttons under the answer: send the id as choiceId.
choices[].idRequiredstringOne of helpful, talk_to_team.
choices[].labelRequiredstring

replies[] with type undefined

FieldTypeDescription
idRequiredstring (uuid)For the patient's own message, the requestId they sent.
sequenceRequiredintegerPosition in the conversation: 1, 2, 3 with no gaps. Order by this.At least 1.
kindRequiredstringOne of text, answer, question, review, emergency, handoff, notice, orders, closed.
fromRequiredobject
from.kindRequiredstringnezer 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.One of patient, nezer, care_team, system.
from.labelRequiredstringThe words to show: "You", "NezerCare", "Care team" (Spanish "Usted", "NezerCare", "Equipo médico"). Staff names are never sent.
priorityRequiredstringOne of normal, emergency.
languageRequiredstringThe language of text.One of en, es.
textRequiredstringAlways present: the words to show. A portal that renders nothing else can print text and stay correct. Never rewrite it.
causedByRequestIdstring (uuid)The patient request this message answers, when it answers one.
attachmentsarray of objectsOn a patient's message: the files they listed with it, as metadata (never the contents).
attachments[].idRequiredstring (uuid)
attachments[].fileNameRequiredstring
attachments[].contentTypeRequiredstringOne of image/jpeg, image/png, image/webp, image/heic, application/pdf.
attachments[].sizeBytesRequiredinteger
createdAtRequiredstring (date-time)
purposeRequiredstringOne of safety_check, intake, team_chat, workflow.
inputRequiredobjectchoice: pick one of choices. text: answer in words (up to maxLength). attachments: add photos with the attachments call, then press done (or skip).
input.typeRequiredstringOne of choice, text, attachments.
input.maxLengthintegerExample: 2000.
input.choicesarray of objects
input.choices[].idRequiredstringSend it as choiceId.One of helpful, talk_to_team, yes, no, unsure, send, send_now, done, skip.
input.choices[].labelRequiredstringThe words on the button, in the message's language.
choicesarray of objectsShortcuts beside the question: send_now ("Send to my care team now", for an urgent concern, at any point) or done and skip for photos.
choices[].idRequiredstringSend it as choiceId.One of helpful, talk_to_team, yes, no, unsure, send, send_now, done, skip.
choices[].labelRequiredstringThe words on the button, in the message's language.

replies[] with type undefined

FieldTypeDescription
idRequiredstring (uuid)For the patient's own message, the requestId they sent.
sequenceRequiredintegerPosition in the conversation: 1, 2, 3 with no gaps. Order by this.At least 1.
kindRequiredstringOne of text, answer, question, review, emergency, handoff, notice, orders, closed.
fromRequiredobject
from.kindRequiredstringnezer 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.One of patient, nezer, care_team, system.
from.labelRequiredstringThe words to show: "You", "NezerCare", "Care team" (Spanish "Usted", "NezerCare", "Equipo médico"). Staff names are never sent.
priorityRequiredstringOne of normal, emergency.
languageRequiredstringThe language of text.One of en, es.
textRequiredstringAlways present: the words to show. A portal that renders nothing else can print text and stay correct. Never rewrite it.
causedByRequestIdstring (uuid)The patient request this message answers, when it answers one.
attachmentsarray of objectsOn a patient's message: the files they listed with it, as metadata (never the contents).
attachments[].idRequiredstring (uuid)
attachments[].fileNameRequiredstring
attachments[].contentTypeRequiredstringOne of image/jpeg, image/png, image/webp, image/heic, application/pdf.
attachments[].sizeBytesRequiredinteger
createdAtRequiredstring (date-time)
statusRequiredstringOne of ready, urgent.
summaryRequiredstring
choicesRequiredarray of objects
choices[].idRequiredstringSend it as choiceId.One of helpful, talk_to_team, yes, no, unsure, send, send_now, done, skip.
choices[].labelRequiredstringThe words on the button, in the message's language.
inputRequiredobject
input.typestringOne of text.
input.maxLengthinteger
input.hintstringExample: Need to change something?.

replies[] with type undefined

FieldTypeDescription
idRequiredstring (uuid)For the patient's own message, the requestId they sent.
sequenceRequiredintegerPosition in the conversation: 1, 2, 3 with no gaps. Order by this.At least 1.
kindRequiredstringOne of text, answer, question, review, emergency, handoff, notice, orders, closed.
fromRequiredobject
from.kindRequiredstringnezer 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.One of patient, nezer, care_team, system.
from.labelRequiredstringThe words to show: "You", "NezerCare", "Care team" (Spanish "Usted", "NezerCare", "Equipo médico"). Staff names are never sent.
priorityRequiredstringOne of normal, emergency.
languageRequiredstringThe language of text.One of en, es.
textRequiredstringAlways present: the words to show. A portal that renders nothing else can print text and stay correct. Never rewrite it.
causedByRequestIdstring (uuid)The patient request this message answers, when it answers one.
attachmentsarray of objectsOn a patient's message: the files they listed with it, as metadata (never the contents).
attachments[].idRequiredstring (uuid)
attachments[].fileNameRequiredstring
attachments[].contentTypeRequiredstringOne of image/jpeg, image/png, image/webp, image/heic, application/pdf.
attachments[].sizeBytesRequiredinteger
createdAtRequiredstring (date-time)
ordersRequiredarray of objects
orders[].idRequiredstring
orders[].statusRequiredstringOne of processing, shipped, delivered, delayed, cancelled.
orders[].statusLabelstring or null
orders[].carrierstring or null
orders[].trackingUrlstring (uri) or null
orders[].estimatedDeliverystring or null
orders[].placedAtstring or null
orders[].itemsRequiredarray of objects
orders[].items[].nameRequiredstring
orders[].items[].quantityRequiredinteger

replies[] with type undefined

FieldTypeDescription
idRequiredstring (uuid)For the patient's own message, the requestId they sent.
sequenceRequiredintegerPosition in the conversation: 1, 2, 3 with no gaps. Order by this.At least 1.
kindRequiredstringOne of text, answer, question, review, emergency, handoff, notice, orders, closed.
fromRequiredobject
from.kindRequiredstringnezer 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.One of patient, nezer, care_team, system.
from.labelRequiredstringThe words to show: "You", "NezerCare", "Care team" (Spanish "Usted", "NezerCare", "Equipo médico"). Staff names are never sent.
priorityRequiredstringOne of normal, emergency.
languageRequiredstringThe language of text.One of en, es.
textRequiredstringAlways present: the words to show. A portal that renders nothing else can print text and stay correct. Never rewrite it.
causedByRequestIdstring (uuid)The patient request this message answers, when it answers one.
attachmentsarray of objectsOn a patient's message: the files they listed with it, as metadata (never the contents).
attachments[].idRequiredstring (uuid)
attachments[].fileNameRequiredstring
attachments[].contentTypeRequiredstringOne of image/jpeg, image/png, image/webp, image/heic, application/pdf.
attachments[].sizeBytesRequiredinteger
createdAtRequiredstring (date-time)
emergencyRequiredobject
emergency.linesRequiredarray of objectsThe ways to call. Thoughts of self-harm add 988.
emergency.lines[].labelRequiredstringExample: Call 911.
emergency.lines[].telRequiredstringExample: tel:911.
emergency.sentToCareTeamRequiredbooleanWhether 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.

replies[] with type undefined

FieldTypeDescription
idRequiredstring (uuid)For the patient's own message, the requestId they sent.
sequenceRequiredintegerPosition in the conversation: 1, 2, 3 with no gaps. Order by this.At least 1.
kindRequiredstringOne of text, answer, question, review, emergency, handoff, notice, orders, closed.
fromRequiredobject
from.kindRequiredstringnezer 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.One of patient, nezer, care_team, system.
from.labelRequiredstringThe words to show: "You", "NezerCare", "Care team" (Spanish "Usted", "NezerCare", "Equipo médico"). Staff names are never sent.
priorityRequiredstringOne of normal, emergency.
languageRequiredstringThe language of text.One of en, es.
textRequiredstringAlways present: the words to show. A portal that renders nothing else can print text and stay correct. Never rewrite it.
causedByRequestIdstring (uuid)The patient request this message answers, when it answers one.
attachmentsarray of objectsOn a patient's message: the files they listed with it, as metadata (never the contents).
attachments[].idRequiredstring (uuid)
attachments[].fileNameRequiredstring
attachments[].contentTypeRequiredstringOne of image/jpeg, image/png, image/webp, image/heic, application/pdf.
attachments[].sizeBytesRequiredinteger
createdAtRequiredstring (date-time)
handoffRequiredobject
handoff.referenceRequiredstringSomething the patient and the team can both quote.Matches ^NC-[0-9A-F]{8}$.
handoff.teamRequiredstringOne of clinical, billing, scheduling, fulfillment, support.
handoff.urgencyRequiredstringOne of routine, urgent.

replies[] with type undefined

FieldTypeDescription
idRequiredstring (uuid)For the patient's own message, the requestId they sent.
sequenceRequiredintegerPosition in the conversation: 1, 2, 3 with no gaps. Order by this.At least 1.
kindRequiredstringOne of text, answer, question, review, emergency, handoff, notice, orders, closed.
fromRequiredobject
from.kindRequiredstringnezer 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.One of patient, nezer, care_team, system.
from.labelRequiredstringThe words to show: "You", "NezerCare", "Care team" (Spanish "Usted", "NezerCare", "Equipo médico"). Staff names are never sent.
priorityRequiredstringOne of normal, emergency.
languageRequiredstringThe language of text.One of en, es.
textRequiredstringAlways present: the words to show. A portal that renders nothing else can print text and stay correct. Never rewrite it.
causedByRequestIdstring (uuid)The patient request this message answers, when it answers one.
attachmentsarray of objectsOn a patient's message: the files they listed with it, as metadata (never the contents).
attachments[].idRequiredstring (uuid)
attachments[].fileNameRequiredstring
attachments[].contentTypeRequiredstringOne of image/jpeg, image/png, image/webp, image/heic, application/pdf.
attachments[].sizeBytesRequiredinteger
createdAtRequiredstring (date-time)
noticeRequiredobject
notice.codeRequiredstringOne of paused.

replies[] with type undefined

FieldTypeDescription
idRequiredstring (uuid)For the patient's own message, the requestId they sent.
sequenceRequiredintegerPosition in the conversation: 1, 2, 3 with no gaps. Order by this.At least 1.
kindRequiredstringOne of text, answer, question, review, emergency, handoff, notice, orders, closed.
fromRequiredobject
from.kindRequiredstringnezer 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.One of patient, nezer, care_team, system.
from.labelRequiredstringThe words to show: "You", "NezerCare", "Care team" (Spanish "Usted", "NezerCare", "Equipo médico"). Staff names are never sent.
priorityRequiredstringOne of normal, emergency.
languageRequiredstringThe language of text.One of en, es.
textRequiredstringAlways present: the words to show. A portal that renders nothing else can print text and stay correct. Never rewrite it.
causedByRequestIdstring (uuid)The patient request this message answers, when it answers one.
attachmentsarray of objectsOn a patient's message: the files they listed with it, as metadata (never the contents).
attachments[].idRequiredstring (uuid)
attachments[].fileNameRequiredstring
attachments[].contentTypeRequiredstringOne of image/jpeg, image/png, image/webp, image/heic, application/pdf.
attachments[].sizeBytesRequiredinteger
createdAtRequiredstring (date-time)
closedRequiredobject
closed.reasonRequiredstringOne of closed.

The 911 guidance, repeated at the top of a response (and of an error) to a message that was an emergency.

FieldTypeDescription
languageRequiredstringOne of en, es.
messageRequiredstringThe reviewed emergency text, in the language the patient wrote in, or the clinic's own message for its extra emergency phrases.
linesRequiredarray of objects
lines[].labelRequiredstringExample: Call 911.
lines[].telRequiredstringExample: tel:911.
201: An everyday question, answered with its sources
{
  "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
}
201: A health concern: the intake asks its safety checks (never an AI answer)
{
  "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
}
201: A request sent straight to the team (when a guided leg can't run, or the workspace is paused)
{
  "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
}
201: A request the clinic built a workflow for: its first question
{
  "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
}
201: An emergency: the notice comes first
{
  "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 response
{
  "code": "INVALID_REQUEST",
  "message": "text must be longer than or equal to 1 characters"
}
401 response
{
  "code": "INVALID_API_CREDENTIAL",
  "message": "API credential is invalid."
}
403 response
{
  "code": "INSUFFICIENT_SCOPE",
  "message": "This API key doesn't have the portal_messaging scope. Create a key with it in Integrations, API keys."
}
404 response
{
  "code": "PATIENT_NOT_FOUND",
  "message": "No patient with this ID in this workspace."
}
409 response
{
  "code": "REQUEST_ID_REUSED",
  "message": "This requestId was already used for a different message. Use a new requestId for a new message."
}
429 response
{
  "code": "RATE_LIMITED",
  "message": "This patient is sending messages faster than allowed. Wait, then retry with the same requestId."
}
500 response
{
  "code": "INTERNAL_ERROR",
  "message": "The message could not be handled. Retry with the same requestId."
}

Read one conversation

GET/v1/patients/{patientId}/conversations/{conversationId}

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.

API key. Authorization: Bearer nzh_prod_… (or a key made earlier, nzh_sb_…): Authentication.

Parameters

FieldTypeDescription
patientIdRequiredpath · string (uuid)The patient's NezerCare ID, from POST /v1/patients/identify. Another workspace's patient, or one that isn't this conversation's, is 404.
conversationIdRequiredpath · string (uuid)The conversation's ID, from the response that started it.
cURL
curl "https://api.nezercare.com/v1/patients/PATIENT_ID/conversations/CONVERSATION_ID" \
  --request GET \
  --header "Authorization: Bearer $NEZER_API_KEY"

Responses

StatusMeaning
200The conversation.
401The API key is missing, invalid, expired or turned off.
403BAA_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.
404CONVERSATION_NOT_FOUND: not this patient's conversation, or another workspace's.
429RATE_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.

200 body

FieldTypeDescription
idRequiredstring (uuid)
patientIdRequiredstring (uuid)
externalConversationIdstring or null
channelRequiredstringOne of portal_api.
statusRequiredstringOne of open, closed.
careStatusRequiredobjectWhere the conversation stands, in the widget's own words only.
careStatus.codeRequiredstringOne of received, in_progress, replied, scheduled, closed.
careStatus.labelRequiredstringExample: New reply from your care team.
appointmentRequiredobjectThe 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.
showCall911RequiredbooleanTrue while an emergency conversation is open: keep the 911 guidance in view.
awaitingRequiredobjectA hint for the composer, never a lock: free text is always accepted.
awaiting.typeRequiredstringWhat the latest message from NezerCare waits for: one of its buttons, words (with choices as shortcuts, if any), or photos (then done or skip).One of none, choice, text, attachments.
awaiting.messageIdstring (uuid)
awaiting.choicesarray of strings
lastSequenceRequiredintegerAt least 0.
versionRequiredintegerIncreases whenever the conversation changes.At least 1.
languageRequiredstringOne of en, es.
safetyRequiredobjectThe 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.
safety.languageRequiredstringOne of en, es.
safety.emergencyLineRequiredstringExample: If this is a medical emergency, call 911..
safety.linesRequiredarray of objects
safety.lines[].labelRequiredstringExample: Call 911.
safety.lines[].telRequiredstringExample: tel:911.
createdAtRequiredstring (date-time)
updatedAtRequiredstring (date-time)
FieldTypeDescription
scheduledForRequiredstring (date-time)The start, in UTC (show it in the patient's own time zone).
visitUrlstring (uri) or nullThe link to join the visit; null for an appointment booked before links were required; absent in a webhook.
200 response
{
  "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 response
{
  "code": "INVALID_API_CREDENTIAL",
  "message": "API credential is invalid."
}
403 response
{
  "code": "INSUFFICIENT_SCOPE",
  "message": "This API key doesn't have the portal_messaging scope. Create a key with it in Integrations, API keys."
}
404 response
{
  "code": "CONVERSATION_NOT_FOUND",
  "message": "No conversation with this ID for this patient."
}
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 that a message was shown

POST/v1/patients/{patientId}/conversations/{conversationId}/messages/{messageId}/delivery

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).

A `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.

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.

API key. Authorization: Bearer nzh_prod_… (or a key made earlier, nzh_sb_…): Authentication.

Parameters

FieldTypeDescription
patientIdRequiredpath · string (uuid)The patient's NezerCare ID, from POST /v1/patients/identify. Another workspace's patient, or one that isn't this conversation's, is 404.
conversationIdRequiredpath · string (uuid)The conversation's ID, from the response that started it.
messageIdRequiredpath · string (uuid)The ID of the message the receipt is for.

Request body

FieldTypeDescription
statusRequiredstringWhat the screen did with the message.One of delivered, read, failed.
errorCodestringWith failed only: a short machine word for why. Never the patient's or the care team's words.Matches ^[A-Za-z0-9_.:-]{1,80}$.
externalMessageIdstringYour own ID for your copy of the message, if you keep one.1–200 characters.
cURL
curl "https://api.nezercare.com/v1/patients/PATIENT_ID/conversations/CONVERSATION_ID/messages/MESSAGE_ID/delivery" \
  --request POST \
  --header "Authorization: Bearer $NEZER_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "status": "delivered"
  }'
Could not be shown
{
  "status": "failed",
  "errorCode": "render_error"
}

Responses

StatusMeaning
200This status was already recorded for the message; nothing changed.
201Recorded.
400INVALID_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.
401The API key is missing, invalid, expired or turned off.
403BAA_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.
404CONVERSATION_NOT_FOUND (not this patient's, or another workspace's) or MESSAGE_NOT_FOUND (not a message of this conversation).
429RATE_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.

200 body

FieldTypeDescription
conversationIdRequiredstring (uuid)
messageIdRequiredstring (uuid)
statusRequiredstringOne of delivered, read, failed.
duplicateRequiredbooleanTrue when this status was already recorded for the message.
recordedAtRequiredstring (date-time)When it was first recorded.
200 response
{
  "conversationId": "4a1c8e90-2b7d-4f36-9c05-7d3e1a6b8f12",
  "messageId": "e6f4b7c2-91a0-4d38-8b5e-3c7a2d9f1e04",
  "status": "delivered",
  "duplicate": true,
  "recordedAt": "2026-10-18T15:02:14.000Z"
}

201 body

FieldTypeDescription
conversationIdRequiredstring (uuid)
messageIdRequiredstring (uuid)
statusRequiredstringOne of delivered, read, failed.
duplicateRequiredbooleanTrue when this status was already recorded for the message.
recordedAtRequiredstring (date-time)When it was first recorded.
201 response
{
  "conversationId": "4a1c8e90-2b7d-4f36-9c05-7d3e1a6b8f12",
  "messageId": "e6f4b7c2-91a0-4d38-8b5e-3c7a2d9f1e04",
  "status": "failed",
  "duplicate": false,
  "recordedAt": "2026-10-18T15:02:14.000Z"
}
400 response
{
  "code": "INVALID_REQUEST",
  "message": "errorCode goes with a failed receipt only."
}
401 response
{
  "code": "INVALID_API_CREDENTIAL",
  "message": "API credential is invalid."
}
403 response
{
  "code": "INSUFFICIENT_SCOPE",
  "message": "This API key doesn't have the portal_messaging scope. Create a key with it in Integrations, API keys."
}
404 response
{
  "code": "MESSAGE_NOT_FOUND",
  "message": "No message with this ID in this conversation."
}
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 the patient's next message

POST/v1/patients/{patientId}/conversations/{conversationId}/messages

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.

Returns 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).

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.

If 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.

Otherwise the message is handled like the widget handles it:

- 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. - A billing, scheduling, fulfillment or support request starts a short guided chat the same way (question, review, handoff). - 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). - An everyday business question is answered from the clinic's own knowledge with its sources (kind: "answer", one credit). - A message in a conversation the team already has goes into that thread, with no reply from NezerCare.

If 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.

Each 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.

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.

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.

Send 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.

A 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.

API key. Authorization: Bearer nzh_prod_… (or a key made earlier, nzh_sb_…): Authentication.

Parameters

FieldTypeDescription
patientIdRequiredpath · string (uuid)The patient's NezerCare ID, from POST /v1/patients/identify. Another workspace's patient, or one that isn't this conversation's, is 404.
conversationIdRequiredpath · string (uuid)The conversation's ID, from the response that started it.

Request body

FieldTypeDescription
requestIdRequiredstring (uuid)
textstring1–10000 characters.
choiceIdstringA button the message under it offers (its choices, or the choices of its input). Needs inReplyTo.One of helpful, talk_to_team, yes, no, unsure, send, send_now, done, skip.
inReplyTostring (uuid)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.
attachmentsarray of objectsFiles 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.Up to 10 items.
attachments[].idRequiredstring (uuid)
languagestringOne of en, es.
cURL
curl "https://api.nezercare.com/v1/patients/PATIENT_ID/conversations/CONVERSATION_ID/messages" \
  --request POST \
  --header "Authorization: Bearer $NEZER_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "requestId": "3f8e2a10-6b4c-4d7a-9e15-8c0b7a2d4e61",
    "text": "Do you ship internationally?"
  }'
The patient pressed a button under a knowledge answer
{
  "requestId": "6c1d9e47-2f03-4a58-b7e6-0d4a8c3f5b92",
  "choiceId": "talk_to_team",
  "inReplyTo": "e6f4b7c2-91a0-4d38-8b5e-3c7a2d9f1e04"
}
The patient answered a safety check
{
  "requestId": "3f8e2a10-6b4c-4d7a-9e15-8c0b7a2d4e61",
  "choiceId": "no",
  "inReplyTo": "b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e"
}
The patient sent the reviewed summary to the care team
{
  "requestId": "7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d",
  "choiceId": "send",
  "inReplyTo": "c3d4e5f6-a7b8-4c9d-8e1f-2a3b4c5d6e7f"
}
The patient added photos (see Add a photo or PDF) and pressed Done
{
  "requestId": "8b9c0d1e-2f3a-4b4c-9d5e-6f7a8b9c0d1e",
  "choiceId": "done",
  "inReplyTo": "d7e8f9a0-b1c2-4d3e-9f4a-5b6c7d8e9f01",
  "attachments": [
    {
      "id": "a0b1c2d3-e4f5-4a6b-8c7d-9e0f1a2b3c4d"
    }
  ]
}

Responses

StatusMeaning
201The patient's message and NezerCare's replies (none, when the message went into a thread the care team already has).
400INVALID_REQUEST: both or neither of text and choiceId, a choiceId without inReplyTo, or a malformed body.
401The API key is missing, invalid, expired or turned off.
403BAA_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.
404PATIENT_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).
409REQUEST_ID_REUSED, TURN_IN_PROGRESS, CONVERSATION_CLOSED, STALE_ANSWER or PATIENT_INACTIVE. An error to an emergency message carries showCall911 and emergency.
429RATE_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.
500A 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.

201 body

FieldTypeDescription
conversationRequiredobject
conversation.idRequiredstring (uuid)
conversation.patientIdRequiredstring (uuid)
conversation.externalConversationIdstring or null
conversation.channelRequiredstringOne of portal_api.
conversation.statusRequiredstringOne of open, closed.
conversation.careStatusRequiredobjectWhere the conversation stands, in the widget's own words only.
conversation.careStatus.codeRequiredstringOne of received, in_progress, replied, scheduled, closed.
conversation.careStatus.labelRequiredstringExample: New reply from your care team.
conversation.appointmentRequiredobjectThe 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.
conversation.showCall911RequiredbooleanTrue while an emergency conversation is open: keep the 911 guidance in view.
conversation.awaitingRequiredobjectA hint for the composer, never a lock: free text is always accepted.
conversation.awaiting.typeRequiredstringWhat the latest message from NezerCare waits for: one of its buttons, words (with choices as shortcuts, if any), or photos (then done or skip).One of none, choice, text, attachments.
conversation.awaiting.messageIdstring (uuid)
conversation.awaiting.choicesarray of strings
conversation.lastSequenceRequiredintegerAt least 0.
conversation.versionRequiredintegerIncreases whenever the conversation changes.At least 1.
conversation.languageRequiredstringOne of en, es.
conversation.safetyRequiredobjectThe 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.
conversation.safety.languageRequiredstringOne of en, es.
conversation.safety.emergencyLineRequiredstringExample: If this is a medical emergency, call 911..
conversation.safety.linesRequiredarray of objects
conversation.safety.lines[].labelRequiredstringExample: Call 911.
conversation.safety.lines[].telRequiredstringExample: tel:911.
conversation.createdAtRequiredstring (date-time)
conversation.updatedAtRequiredstring (date-time)
messageRequiredobjectOne message of a conversation. text is always the words to show; the rest depends on kind.
repliesRequiredarray of objectsNezerCare'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.
showCall911RequiredbooleanTrue when the message was an emergency.
emergencyRequiredobject
duplicateRequiredbooleanTrue 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).
FieldTypeDescription
scheduledForRequiredstring (date-time)The start, in UTC (show it in the patient's own time zone).
visitUrlstring (uri) or nullThe link to join the visit; null for an appointment booked before links were required; absent in a webhook.
FieldTypeDescription
idRequiredstring (uuid)For the patient's own message, the requestId they sent.
sequenceRequiredintegerPosition in the conversation: 1, 2, 3 with no gaps. Order by this.At least 1.
kindRequiredstringOne of text, answer, question, review, emergency, handoff, notice, orders, closed.
fromRequiredobject
from.kindRequiredstringnezer 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.One of patient, nezer, care_team, system.
from.labelRequiredstringThe words to show: "You", "NezerCare", "Care team" (Spanish "Usted", "NezerCare", "Equipo médico"). Staff names are never sent.
priorityRequiredstringOne of normal, emergency.
languageRequiredstringThe language of text.One of en, es.
textRequiredstringAlways present: the words to show. A portal that renders nothing else can print text and stay correct. Never rewrite it.
causedByRequestIdstring (uuid)The patient request this message answers, when it answers one.
attachmentsarray of objectsOn a patient's message: the files they listed with it, as metadata (never the contents).
attachments[].idRequiredstring (uuid)
attachments[].fileNameRequiredstring
attachments[].contentTypeRequiredstringOne of image/jpeg, image/png, image/webp, image/heic, application/pdf.
attachments[].sizeBytesRequiredinteger
createdAtRequiredstring (date-time)
FieldTypeDescription
idRequiredstring (uuid)For the patient's own message, the requestId they sent.
sequenceRequiredintegerPosition in the conversation: 1, 2, 3 with no gaps. Order by this.At least 1.
kindRequiredstringOne of text, answer, question, review, emergency, handoff, notice, orders, closed.
fromRequiredobject
from.kindRequiredstringnezer 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.One of patient, nezer, care_team, system.
from.labelRequiredstringThe words to show: "You", "NezerCare", "Care team" (Spanish "Usted", "NezerCare", "Equipo médico"). Staff names are never sent.
priorityRequiredstringOne of normal, emergency.
languageRequiredstringThe language of text.One of en, es.
textRequiredstringAlways present: the words to show. A portal that renders nothing else can print text and stay correct. Never rewrite it.
causedByRequestIdstring (uuid)The patient request this message answers, when it answers one.
attachmentsarray of objectsOn a patient's message: the files they listed with it, as metadata (never the contents).
attachments[].idRequiredstring (uuid)
attachments[].fileNameRequiredstring
attachments[].contentTypeRequiredstringOne of image/jpeg, image/png, image/webp, image/heic, application/pdf.
attachments[].sizeBytesRequiredinteger
createdAtRequiredstring (date-time)
answerIdRequiredstring (uuid)
sourcesRequiredarray of objectsWhere the answer came from. Show them.
sources[].titleRequiredstring
sources[].urlRequiredstring (uri) or null
actionsRequiredarray of objectsAt most a Book button, with an https address on the clinic's site. Never a contact button for a signed-in patient.
actions[].kindRequiredstringOne of book.
actions[].urlRequiredstring (uri)
actions[].labelstringOne of demo, appointment, consultation, call.
choicesRequiredarray of objectsThe buttons under the answer: send the id as choiceId.
choices[].idRequiredstringOne of helpful, talk_to_team.
choices[].labelRequiredstring
FieldTypeDescription
idRequiredstring (uuid)For the patient's own message, the requestId they sent.
sequenceRequiredintegerPosition in the conversation: 1, 2, 3 with no gaps. Order by this.At least 1.
kindRequiredstringOne of text, answer, question, review, emergency, handoff, notice, orders, closed.
fromRequiredobject
from.kindRequiredstringnezer 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.One of patient, nezer, care_team, system.
from.labelRequiredstringThe words to show: "You", "NezerCare", "Care team" (Spanish "Usted", "NezerCare", "Equipo médico"). Staff names are never sent.
priorityRequiredstringOne of normal, emergency.
languageRequiredstringThe language of text.One of en, es.
textRequiredstringAlways present: the words to show. A portal that renders nothing else can print text and stay correct. Never rewrite it.
causedByRequestIdstring (uuid)The patient request this message answers, when it answers one.
attachmentsarray of objectsOn a patient's message: the files they listed with it, as metadata (never the contents).
attachments[].idRequiredstring (uuid)
attachments[].fileNameRequiredstring
attachments[].contentTypeRequiredstringOne of image/jpeg, image/png, image/webp, image/heic, application/pdf.
attachments[].sizeBytesRequiredinteger
createdAtRequiredstring (date-time)
purposeRequiredstringOne of safety_check, intake, team_chat, workflow.
inputRequiredobjectchoice: pick one of choices. text: answer in words (up to maxLength). attachments: add photos with the attachments call, then press done (or skip).
input.typeRequiredstringOne of choice, text, attachments.
input.maxLengthintegerExample: 2000.
input.choicesarray of objects
input.choices[].idRequiredstringSend it as choiceId.One of helpful, talk_to_team, yes, no, unsure, send, send_now, done, skip.
input.choices[].labelRequiredstringThe words on the button, in the message's language.
choicesarray of objectsShortcuts beside the question: send_now ("Send to my care team now", for an urgent concern, at any point) or done and skip for photos.
choices[].idRequiredstringSend it as choiceId.One of helpful, talk_to_team, yes, no, unsure, send, send_now, done, skip.
choices[].labelRequiredstringThe words on the button, in the message's language.
FieldTypeDescription
idRequiredstring (uuid)For the patient's own message, the requestId they sent.
sequenceRequiredintegerPosition in the conversation: 1, 2, 3 with no gaps. Order by this.At least 1.
kindRequiredstringOne of text, answer, question, review, emergency, handoff, notice, orders, closed.
fromRequiredobject
from.kindRequiredstringnezer 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.One of patient, nezer, care_team, system.
from.labelRequiredstringThe words to show: "You", "NezerCare", "Care team" (Spanish "Usted", "NezerCare", "Equipo médico"). Staff names are never sent.
priorityRequiredstringOne of normal, emergency.
languageRequiredstringThe language of text.One of en, es.
textRequiredstringAlways present: the words to show. A portal that renders nothing else can print text and stay correct. Never rewrite it.
causedByRequestIdstring (uuid)The patient request this message answers, when it answers one.
attachmentsarray of objectsOn a patient's message: the files they listed with it, as metadata (never the contents).
attachments[].idRequiredstring (uuid)
attachments[].fileNameRequiredstring
attachments[].contentTypeRequiredstringOne of image/jpeg, image/png, image/webp, image/heic, application/pdf.
attachments[].sizeBytesRequiredinteger
createdAtRequiredstring (date-time)
statusRequiredstringOne of ready, urgent.
summaryRequiredstring
choicesRequiredarray of objects
choices[].idRequiredstringSend it as choiceId.One of helpful, talk_to_team, yes, no, unsure, send, send_now, done, skip.
choices[].labelRequiredstringThe words on the button, in the message's language.
inputRequiredobject
input.typestringOne of text.
input.maxLengthinteger
input.hintstringExample: Need to change something?.
FieldTypeDescription
idRequiredstring (uuid)For the patient's own message, the requestId they sent.
sequenceRequiredintegerPosition in the conversation: 1, 2, 3 with no gaps. Order by this.At least 1.
kindRequiredstringOne of text, answer, question, review, emergency, handoff, notice, orders, closed.
fromRequiredobject
from.kindRequiredstringnezer 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.One of patient, nezer, care_team, system.
from.labelRequiredstringThe words to show: "You", "NezerCare", "Care team" (Spanish "Usted", "NezerCare", "Equipo médico"). Staff names are never sent.
priorityRequiredstringOne of normal, emergency.
languageRequiredstringThe language of text.One of en, es.
textRequiredstringAlways present: the words to show. A portal that renders nothing else can print text and stay correct. Never rewrite it.
causedByRequestIdstring (uuid)The patient request this message answers, when it answers one.
attachmentsarray of objectsOn a patient's message: the files they listed with it, as metadata (never the contents).
attachments[].idRequiredstring (uuid)
attachments[].fileNameRequiredstring
attachments[].contentTypeRequiredstringOne of image/jpeg, image/png, image/webp, image/heic, application/pdf.
attachments[].sizeBytesRequiredinteger
createdAtRequiredstring (date-time)
ordersRequiredarray of objects
orders[].idRequiredstring
orders[].statusRequiredstringOne of processing, shipped, delivered, delayed, cancelled.
orders[].statusLabelstring or null
orders[].carrierstring or null
orders[].trackingUrlstring (uri) or null
orders[].estimatedDeliverystring or null
orders[].placedAtstring or null
orders[].itemsRequiredarray of objects
orders[].items[].nameRequiredstring
orders[].items[].quantityRequiredinteger
FieldTypeDescription
idRequiredstring (uuid)For the patient's own message, the requestId they sent.
sequenceRequiredintegerPosition in the conversation: 1, 2, 3 with no gaps. Order by this.At least 1.
kindRequiredstringOne of text, answer, question, review, emergency, handoff, notice, orders, closed.
fromRequiredobject
from.kindRequiredstringnezer 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.One of patient, nezer, care_team, system.
from.labelRequiredstringThe words to show: "You", "NezerCare", "Care team" (Spanish "Usted", "NezerCare", "Equipo médico"). Staff names are never sent.
priorityRequiredstringOne of normal, emergency.
languageRequiredstringThe language of text.One of en, es.
textRequiredstringAlways present: the words to show. A portal that renders nothing else can print text and stay correct. Never rewrite it.
causedByRequestIdstring (uuid)The patient request this message answers, when it answers one.
attachmentsarray of objectsOn a patient's message: the files they listed with it, as metadata (never the contents).
attachments[].idRequiredstring (uuid)
attachments[].fileNameRequiredstring
attachments[].contentTypeRequiredstringOne of image/jpeg, image/png, image/webp, image/heic, application/pdf.
attachments[].sizeBytesRequiredinteger
createdAtRequiredstring (date-time)
emergencyRequiredobject
emergency.linesRequiredarray of objectsThe ways to call. Thoughts of self-harm add 988.
emergency.lines[].labelRequiredstringExample: Call 911.
emergency.lines[].telRequiredstringExample: tel:911.
emergency.sentToCareTeamRequiredbooleanWhether 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.
FieldTypeDescription
idRequiredstring (uuid)For the patient's own message, the requestId they sent.
sequenceRequiredintegerPosition in the conversation: 1, 2, 3 with no gaps. Order by this.At least 1.
kindRequiredstringOne of text, answer, question, review, emergency, handoff, notice, orders, closed.
fromRequiredobject
from.kindRequiredstringnezer 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.One of patient, nezer, care_team, system.
from.labelRequiredstringThe words to show: "You", "NezerCare", "Care team" (Spanish "Usted", "NezerCare", "Equipo médico"). Staff names are never sent.
priorityRequiredstringOne of normal, emergency.
languageRequiredstringThe language of text.One of en, es.
textRequiredstringAlways present: the words to show. A portal that renders nothing else can print text and stay correct. Never rewrite it.
causedByRequestIdstring (uuid)The patient request this message answers, when it answers one.
attachmentsarray of objectsOn a patient's message: the files they listed with it, as metadata (never the contents).
attachments[].idRequiredstring (uuid)
attachments[].fileNameRequiredstring
attachments[].contentTypeRequiredstringOne of image/jpeg, image/png, image/webp, image/heic, application/pdf.
attachments[].sizeBytesRequiredinteger
createdAtRequiredstring (date-time)
handoffRequiredobject
handoff.referenceRequiredstringSomething the patient and the team can both quote.Matches ^NC-[0-9A-F]{8}$.
handoff.teamRequiredstringOne of clinical, billing, scheduling, fulfillment, support.
handoff.urgencyRequiredstringOne of routine, urgent.
FieldTypeDescription
idRequiredstring (uuid)For the patient's own message, the requestId they sent.
sequenceRequiredintegerPosition in the conversation: 1, 2, 3 with no gaps. Order by this.At least 1.
kindRequiredstringOne of text, answer, question, review, emergency, handoff, notice, orders, closed.
fromRequiredobject
from.kindRequiredstringnezer 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.One of patient, nezer, care_team, system.
from.labelRequiredstringThe words to show: "You", "NezerCare", "Care team" (Spanish "Usted", "NezerCare", "Equipo médico"). Staff names are never sent.
priorityRequiredstringOne of normal, emergency.
languageRequiredstringThe language of text.One of en, es.
textRequiredstringAlways present: the words to show. A portal that renders nothing else can print text and stay correct. Never rewrite it.
causedByRequestIdstring (uuid)The patient request this message answers, when it answers one.
attachmentsarray of objectsOn a patient's message: the files they listed with it, as metadata (never the contents).
attachments[].idRequiredstring (uuid)
attachments[].fileNameRequiredstring
attachments[].contentTypeRequiredstringOne of image/jpeg, image/png, image/webp, image/heic, application/pdf.
attachments[].sizeBytesRequiredinteger
createdAtRequiredstring (date-time)
noticeRequiredobject
notice.codeRequiredstringOne of paused.
FieldTypeDescription
idRequiredstring (uuid)For the patient's own message, the requestId they sent.
sequenceRequiredintegerPosition in the conversation: 1, 2, 3 with no gaps. Order by this.At least 1.
kindRequiredstringOne of text, answer, question, review, emergency, handoff, notice, orders, closed.
fromRequiredobject
from.kindRequiredstringnezer 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.One of patient, nezer, care_team, system.
from.labelRequiredstringThe words to show: "You", "NezerCare", "Care team" (Spanish "Usted", "NezerCare", "Equipo médico"). Staff names are never sent.
priorityRequiredstringOne of normal, emergency.
languageRequiredstringThe language of text.One of en, es.
textRequiredstringAlways present: the words to show. A portal that renders nothing else can print text and stay correct. Never rewrite it.
causedByRequestIdstring (uuid)The patient request this message answers, when it answers one.
attachmentsarray of objectsOn a patient's message: the files they listed with it, as metadata (never the contents).
attachments[].idRequiredstring (uuid)
attachments[].fileNameRequiredstring
attachments[].contentTypeRequiredstringOne of image/jpeg, image/png, image/webp, image/heic, application/pdf.
attachments[].sizeBytesRequiredinteger
createdAtRequiredstring (date-time)
closedRequiredobject
closed.reasonRequiredstringOne of closed.

replies[] with type undefined

FieldTypeDescription
idRequiredstring (uuid)For the patient's own message, the requestId they sent.
sequenceRequiredintegerPosition in the conversation: 1, 2, 3 with no gaps. Order by this.At least 1.
kindRequiredstringOne of text, answer, question, review, emergency, handoff, notice, orders, closed.
fromRequiredobject
from.kindRequiredstringnezer 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.One of patient, nezer, care_team, system.
from.labelRequiredstringThe words to show: "You", "NezerCare", "Care team" (Spanish "Usted", "NezerCare", "Equipo médico"). Staff names are never sent.
priorityRequiredstringOne of normal, emergency.
languageRequiredstringThe language of text.One of en, es.
textRequiredstringAlways present: the words to show. A portal that renders nothing else can print text and stay correct. Never rewrite it.
causedByRequestIdstring (uuid)The patient request this message answers, when it answers one.
attachmentsarray of objectsOn a patient's message: the files they listed with it, as metadata (never the contents).
attachments[].idRequiredstring (uuid)
attachments[].fileNameRequiredstring
attachments[].contentTypeRequiredstringOne of image/jpeg, image/png, image/webp, image/heic, application/pdf.
attachments[].sizeBytesRequiredinteger
createdAtRequiredstring (date-time)

replies[] with type undefined

FieldTypeDescription
idRequiredstring (uuid)For the patient's own message, the requestId they sent.
sequenceRequiredintegerPosition in the conversation: 1, 2, 3 with no gaps. Order by this.At least 1.
kindRequiredstringOne of text, answer, question, review, emergency, handoff, notice, orders, closed.
fromRequiredobject
from.kindRequiredstringnezer 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.One of patient, nezer, care_team, system.
from.labelRequiredstringThe words to show: "You", "NezerCare", "Care team" (Spanish "Usted", "NezerCare", "Equipo médico"). Staff names are never sent.
priorityRequiredstringOne of normal, emergency.
languageRequiredstringThe language of text.One of en, es.
textRequiredstringAlways present: the words to show. A portal that renders nothing else can print text and stay correct. Never rewrite it.
causedByRequestIdstring (uuid)The patient request this message answers, when it answers one.
attachmentsarray of objectsOn a patient's message: the files they listed with it, as metadata (never the contents).
attachments[].idRequiredstring (uuid)
attachments[].fileNameRequiredstring
attachments[].contentTypeRequiredstringOne of image/jpeg, image/png, image/webp, image/heic, application/pdf.
attachments[].sizeBytesRequiredinteger
createdAtRequiredstring (date-time)
answerIdRequiredstring (uuid)
sourcesRequiredarray of objectsWhere the answer came from. Show them.
sources[].titleRequiredstring
sources[].urlRequiredstring (uri) or null
actionsRequiredarray of objectsAt most a Book button, with an https address on the clinic's site. Never a contact button for a signed-in patient.
actions[].kindRequiredstringOne of book.
actions[].urlRequiredstring (uri)
actions[].labelstringOne of demo, appointment, consultation, call.
choicesRequiredarray of objectsThe buttons under the answer: send the id as choiceId.
choices[].idRequiredstringOne of helpful, talk_to_team.
choices[].labelRequiredstring

replies[] with type undefined

FieldTypeDescription
idRequiredstring (uuid)For the patient's own message, the requestId they sent.
sequenceRequiredintegerPosition in the conversation: 1, 2, 3 with no gaps. Order by this.At least 1.
kindRequiredstringOne of text, answer, question, review, emergency, handoff, notice, orders, closed.
fromRequiredobject
from.kindRequiredstringnezer 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.One of patient, nezer, care_team, system.
from.labelRequiredstringThe words to show: "You", "NezerCare", "Care team" (Spanish "Usted", "NezerCare", "Equipo médico"). Staff names are never sent.
priorityRequiredstringOne of normal, emergency.
languageRequiredstringThe language of text.One of en, es.
textRequiredstringAlways present: the words to show. A portal that renders nothing else can print text and stay correct. Never rewrite it.
causedByRequestIdstring (uuid)The patient request this message answers, when it answers one.
attachmentsarray of objectsOn a patient's message: the files they listed with it, as metadata (never the contents).
attachments[].idRequiredstring (uuid)
attachments[].fileNameRequiredstring
attachments[].contentTypeRequiredstringOne of image/jpeg, image/png, image/webp, image/heic, application/pdf.
attachments[].sizeBytesRequiredinteger
createdAtRequiredstring (date-time)
purposeRequiredstringOne of safety_check, intake, team_chat, workflow.
inputRequiredobjectchoice: pick one of choices. text: answer in words (up to maxLength). attachments: add photos with the attachments call, then press done (or skip).
input.typeRequiredstringOne of choice, text, attachments.
input.maxLengthintegerExample: 2000.
input.choicesarray of objects
input.choices[].idRequiredstringSend it as choiceId.One of helpful, talk_to_team, yes, no, unsure, send, send_now, done, skip.
input.choices[].labelRequiredstringThe words on the button, in the message's language.
choicesarray of objectsShortcuts beside the question: send_now ("Send to my care team now", for an urgent concern, at any point) or done and skip for photos.
choices[].idRequiredstringSend it as choiceId.One of helpful, talk_to_team, yes, no, unsure, send, send_now, done, skip.
choices[].labelRequiredstringThe words on the button, in the message's language.

replies[] with type undefined

FieldTypeDescription
idRequiredstring (uuid)For the patient's own message, the requestId they sent.
sequenceRequiredintegerPosition in the conversation: 1, 2, 3 with no gaps. Order by this.At least 1.
kindRequiredstringOne of text, answer, question, review, emergency, handoff, notice, orders, closed.
fromRequiredobject
from.kindRequiredstringnezer 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.One of patient, nezer, care_team, system.
from.labelRequiredstringThe words to show: "You", "NezerCare", "Care team" (Spanish "Usted", "NezerCare", "Equipo médico"). Staff names are never sent.
priorityRequiredstringOne of normal, emergency.
languageRequiredstringThe language of text.One of en, es.
textRequiredstringAlways present: the words to show. A portal that renders nothing else can print text and stay correct. Never rewrite it.
causedByRequestIdstring (uuid)The patient request this message answers, when it answers one.
attachmentsarray of objectsOn a patient's message: the files they listed with it, as metadata (never the contents).
attachments[].idRequiredstring (uuid)
attachments[].fileNameRequiredstring
attachments[].contentTypeRequiredstringOne of image/jpeg, image/png, image/webp, image/heic, application/pdf.
attachments[].sizeBytesRequiredinteger
createdAtRequiredstring (date-time)
statusRequiredstringOne of ready, urgent.
summaryRequiredstring
choicesRequiredarray of objects
choices[].idRequiredstringSend it as choiceId.One of helpful, talk_to_team, yes, no, unsure, send, send_now, done, skip.
choices[].labelRequiredstringThe words on the button, in the message's language.
inputRequiredobject
input.typestringOne of text.
input.maxLengthinteger
input.hintstringExample: Need to change something?.

replies[] with type undefined

FieldTypeDescription
idRequiredstring (uuid)For the patient's own message, the requestId they sent.
sequenceRequiredintegerPosition in the conversation: 1, 2, 3 with no gaps. Order by this.At least 1.
kindRequiredstringOne of text, answer, question, review, emergency, handoff, notice, orders, closed.
fromRequiredobject
from.kindRequiredstringnezer 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.One of patient, nezer, care_team, system.
from.labelRequiredstringThe words to show: "You", "NezerCare", "Care team" (Spanish "Usted", "NezerCare", "Equipo médico"). Staff names are never sent.
priorityRequiredstringOne of normal, emergency.
languageRequiredstringThe language of text.One of en, es.
textRequiredstringAlways present: the words to show. A portal that renders nothing else can print text and stay correct. Never rewrite it.
causedByRequestIdstring (uuid)The patient request this message answers, when it answers one.
attachmentsarray of objectsOn a patient's message: the files they listed with it, as metadata (never the contents).
attachments[].idRequiredstring (uuid)
attachments[].fileNameRequiredstring
attachments[].contentTypeRequiredstringOne of image/jpeg, image/png, image/webp, image/heic, application/pdf.
attachments[].sizeBytesRequiredinteger
createdAtRequiredstring (date-time)
ordersRequiredarray of objects
orders[].idRequiredstring
orders[].statusRequiredstringOne of processing, shipped, delivered, delayed, cancelled.
orders[].statusLabelstring or null
orders[].carrierstring or null
orders[].trackingUrlstring (uri) or null
orders[].estimatedDeliverystring or null
orders[].placedAtstring or null
orders[].itemsRequiredarray of objects
orders[].items[].nameRequiredstring
orders[].items[].quantityRequiredinteger

replies[] with type undefined

FieldTypeDescription
idRequiredstring (uuid)For the patient's own message, the requestId they sent.
sequenceRequiredintegerPosition in the conversation: 1, 2, 3 with no gaps. Order by this.At least 1.
kindRequiredstringOne of text, answer, question, review, emergency, handoff, notice, orders, closed.
fromRequiredobject
from.kindRequiredstringnezer 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.One of patient, nezer, care_team, system.
from.labelRequiredstringThe words to show: "You", "NezerCare", "Care team" (Spanish "Usted", "NezerCare", "Equipo médico"). Staff names are never sent.
priorityRequiredstringOne of normal, emergency.
languageRequiredstringThe language of text.One of en, es.
textRequiredstringAlways present: the words to show. A portal that renders nothing else can print text and stay correct. Never rewrite it.
causedByRequestIdstring (uuid)The patient request this message answers, when it answers one.
attachmentsarray of objectsOn a patient's message: the files they listed with it, as metadata (never the contents).
attachments[].idRequiredstring (uuid)
attachments[].fileNameRequiredstring
attachments[].contentTypeRequiredstringOne of image/jpeg, image/png, image/webp, image/heic, application/pdf.
attachments[].sizeBytesRequiredinteger
createdAtRequiredstring (date-time)
emergencyRequiredobject
emergency.linesRequiredarray of objectsThe ways to call. Thoughts of self-harm add 988.
emergency.lines[].labelRequiredstringExample: Call 911.
emergency.lines[].telRequiredstringExample: tel:911.
emergency.sentToCareTeamRequiredbooleanWhether 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.

replies[] with type undefined

FieldTypeDescription
idRequiredstring (uuid)For the patient's own message, the requestId they sent.
sequenceRequiredintegerPosition in the conversation: 1, 2, 3 with no gaps. Order by this.At least 1.
kindRequiredstringOne of text, answer, question, review, emergency, handoff, notice, orders, closed.
fromRequiredobject
from.kindRequiredstringnezer 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.One of patient, nezer, care_team, system.
from.labelRequiredstringThe words to show: "You", "NezerCare", "Care team" (Spanish "Usted", "NezerCare", "Equipo médico"). Staff names are never sent.
priorityRequiredstringOne of normal, emergency.
languageRequiredstringThe language of text.One of en, es.
textRequiredstringAlways present: the words to show. A portal that renders nothing else can print text and stay correct. Never rewrite it.
causedByRequestIdstring (uuid)The patient request this message answers, when it answers one.
attachmentsarray of objectsOn a patient's message: the files they listed with it, as metadata (never the contents).
attachments[].idRequiredstring (uuid)
attachments[].fileNameRequiredstring
attachments[].contentTypeRequiredstringOne of image/jpeg, image/png, image/webp, image/heic, application/pdf.
attachments[].sizeBytesRequiredinteger
createdAtRequiredstring (date-time)
handoffRequiredobject
handoff.referenceRequiredstringSomething the patient and the team can both quote.Matches ^NC-[0-9A-F]{8}$.
handoff.teamRequiredstringOne of clinical, billing, scheduling, fulfillment, support.
handoff.urgencyRequiredstringOne of routine, urgent.

replies[] with type undefined

FieldTypeDescription
idRequiredstring (uuid)For the patient's own message, the requestId they sent.
sequenceRequiredintegerPosition in the conversation: 1, 2, 3 with no gaps. Order by this.At least 1.
kindRequiredstringOne of text, answer, question, review, emergency, handoff, notice, orders, closed.
fromRequiredobject
from.kindRequiredstringnezer 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.One of patient, nezer, care_team, system.
from.labelRequiredstringThe words to show: "You", "NezerCare", "Care team" (Spanish "Usted", "NezerCare", "Equipo médico"). Staff names are never sent.
priorityRequiredstringOne of normal, emergency.
languageRequiredstringThe language of text.One of en, es.
textRequiredstringAlways present: the words to show. A portal that renders nothing else can print text and stay correct. Never rewrite it.
causedByRequestIdstring (uuid)The patient request this message answers, when it answers one.
attachmentsarray of objectsOn a patient's message: the files they listed with it, as metadata (never the contents).
attachments[].idRequiredstring (uuid)
attachments[].fileNameRequiredstring
attachments[].contentTypeRequiredstringOne of image/jpeg, image/png, image/webp, image/heic, application/pdf.
attachments[].sizeBytesRequiredinteger
createdAtRequiredstring (date-time)
noticeRequiredobject
notice.codeRequiredstringOne of paused.

replies[] with type undefined

FieldTypeDescription
idRequiredstring (uuid)For the patient's own message, the requestId they sent.
sequenceRequiredintegerPosition in the conversation: 1, 2, 3 with no gaps. Order by this.At least 1.
kindRequiredstringOne of text, answer, question, review, emergency, handoff, notice, orders, closed.
fromRequiredobject
from.kindRequiredstringnezer 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.One of patient, nezer, care_team, system.
from.labelRequiredstringThe words to show: "You", "NezerCare", "Care team" (Spanish "Usted", "NezerCare", "Equipo médico"). Staff names are never sent.
priorityRequiredstringOne of normal, emergency.
languageRequiredstringThe language of text.One of en, es.
textRequiredstringAlways present: the words to show. A portal that renders nothing else can print text and stay correct. Never rewrite it.
causedByRequestIdstring (uuid)The patient request this message answers, when it answers one.
attachmentsarray of objectsOn a patient's message: the files they listed with it, as metadata (never the contents).
attachments[].idRequiredstring (uuid)
attachments[].fileNameRequiredstring
attachments[].contentTypeRequiredstringOne of image/jpeg, image/png, image/webp, image/heic, application/pdf.
attachments[].sizeBytesRequiredinteger
createdAtRequiredstring (date-time)
closedRequiredobject
closed.reasonRequiredstringOne of closed.

The 911 guidance, repeated at the top of a response (and of an error) to a message that was an emergency.

FieldTypeDescription
languageRequiredstringOne of en, es.
messageRequiredstringThe reviewed emergency text, in the language the patient wrote in, or the clinic's own message for its extra emergency phrases.
linesRequiredarray of objects
lines[].labelRequiredstringExample: Call 911.
lines[].telRequiredstringExample: tel:911.
201: A message in a conversation the care team has: no reply from NezerCare
{
  "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
}
201: An approved question of the Health concerns intake
{
  "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
}
201: "Does this look right?": the summary, built from the patient's own words
{
  "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
}
201: Sent: the care team has it
{
  "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
}
201: A workflow asks for photos
{
  "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
}
201: An order lookup's orders, then the offer of a person
{
  "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 response
{
  "code": "INVALID_REQUEST",
  "message": "Send exactly one of text and choiceId."
}
401 response
{
  "code": "INVALID_API_CREDENTIAL",
  "message": "API credential is invalid."
}
403 response
{
  "code": "INSUFFICIENT_SCOPE",
  "message": "This API key doesn't have the portal_messaging scope. Create a key with it in Integrations, API keys."
}
404 response
{
  "code": "CONVERSATION_NOT_FOUND",
  "message": "No conversation with this ID for this patient."
}
409 response
{
  "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 response
{
  "code": "RATE_LIMITED",
  "message": "This patient is sending messages faster than allowed. Wait, then retry with the same requestId."
}
500 response
{
  "code": "INTERNAL_ERROR",
  "message": "The message could not be handled. Retry with the same requestId."
}

Read the conversation

GET/v1/patients/{patientId}/conversations/{conversationId}/messages

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.

The 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.

API key. Authorization: Bearer nzh_prod_… (or a key made earlier, nzh_sb_…): Authentication.

Parameters

FieldTypeDescription
patientIdRequiredpath · string (uuid)The patient's NezerCare ID, from POST /v1/patients/identify. Another workspace's patient, or one that isn't this conversation's, is 404.
conversationIdRequiredpath · string (uuid)The conversation's ID, from the response that started it.
afterSequencequery · integerThe last sequence you have; the default is 0 (everything).At least 0.Defaults to 0.
limitquery · integerAt most this many messages (up to 250).1 to 250.Defaults to 100.
cURL
curl "https://api.nezercare.com/v1/patients/PATIENT_ID/conversations/CONVERSATION_ID/messages?afterSequence=0&limit=100" \
  --request GET \
  --header "Authorization: Bearer $NEZER_API_KEY"

Responses

StatusMeaning
200Messages after afterSequence.
400INVALID_REQUEST.
401The API key is missing, invalid, expired or turned off.
403BAA_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.
404CONVERSATION_NOT_FOUND: not this patient's conversation, or another workspace's.
429RATE_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.

200 body

FieldTypeDescription
messagesRequiredarray of objects
lastSequenceRequiredintegerThe conversation's newest sequence.At least 0.
hasMoreRequiredbooleanTrue when more messages follow the last one returned: ask again with its sequence.
conversationRequiredobject
conversation.idRequiredstring (uuid)
conversation.patientIdRequiredstring (uuid)
conversation.externalConversationIdstring or null
conversation.channelRequiredstringOne of portal_api.
conversation.statusRequiredstringOne of open, closed.
conversation.careStatusRequiredobjectWhere the conversation stands, in the widget's own words only.
conversation.careStatus.codeRequiredstringOne of received, in_progress, replied, scheduled, closed.
conversation.careStatus.labelRequiredstringExample: New reply from your care team.
conversation.appointmentRequiredobjectThe 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.
conversation.showCall911RequiredbooleanTrue while an emergency conversation is open: keep the 911 guidance in view.
conversation.awaitingRequiredobjectA hint for the composer, never a lock: free text is always accepted.
conversation.awaiting.typeRequiredstringWhat the latest message from NezerCare waits for: one of its buttons, words (with choices as shortcuts, if any), or photos (then done or skip).One of none, choice, text, attachments.
conversation.awaiting.messageIdstring (uuid)
conversation.awaiting.choicesarray of strings
conversation.lastSequenceRequiredintegerAt least 0.
conversation.versionRequiredintegerIncreases whenever the conversation changes.At least 1.
conversation.languageRequiredstringOne of en, es.
conversation.safetyRequiredobjectThe 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.
conversation.safety.languageRequiredstringOne of en, es.
conversation.safety.emergencyLineRequiredstringExample: If this is a medical emergency, call 911..
conversation.safety.linesRequiredarray of objects
conversation.safety.lines[].labelRequiredstringExample: Call 911.
conversation.safety.lines[].telRequiredstringExample: tel:911.
conversation.createdAtRequiredstring (date-time)
conversation.updatedAtRequiredstring (date-time)

messages[] with type undefined

FieldTypeDescription
idRequiredstring (uuid)For the patient's own message, the requestId they sent.
sequenceRequiredintegerPosition in the conversation: 1, 2, 3 with no gaps. Order by this.At least 1.
kindRequiredstringOne of text, answer, question, review, emergency, handoff, notice, orders, closed.
fromRequiredobject
from.kindRequiredstringnezer 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.One of patient, nezer, care_team, system.
from.labelRequiredstringThe words to show: "You", "NezerCare", "Care team" (Spanish "Usted", "NezerCare", "Equipo médico"). Staff names are never sent.
priorityRequiredstringOne of normal, emergency.
languageRequiredstringThe language of text.One of en, es.
textRequiredstringAlways present: the words to show. A portal that renders nothing else can print text and stay correct. Never rewrite it.
causedByRequestIdstring (uuid)The patient request this message answers, when it answers one.
attachmentsarray of objectsOn a patient's message: the files they listed with it, as metadata (never the contents).
attachments[].idRequiredstring (uuid)
attachments[].fileNameRequiredstring
attachments[].contentTypeRequiredstringOne of image/jpeg, image/png, image/webp, image/heic, application/pdf.
attachments[].sizeBytesRequiredinteger
createdAtRequiredstring (date-time)

messages[] with type undefined

FieldTypeDescription
idRequiredstring (uuid)For the patient's own message, the requestId they sent.
sequenceRequiredintegerPosition in the conversation: 1, 2, 3 with no gaps. Order by this.At least 1.
kindRequiredstringOne of text, answer, question, review, emergency, handoff, notice, orders, closed.
fromRequiredobject
from.kindRequiredstringnezer 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.One of patient, nezer, care_team, system.
from.labelRequiredstringThe words to show: "You", "NezerCare", "Care team" (Spanish "Usted", "NezerCare", "Equipo médico"). Staff names are never sent.
priorityRequiredstringOne of normal, emergency.
languageRequiredstringThe language of text.One of en, es.
textRequiredstringAlways present: the words to show. A portal that renders nothing else can print text and stay correct. Never rewrite it.
causedByRequestIdstring (uuid)The patient request this message answers, when it answers one.
attachmentsarray of objectsOn a patient's message: the files they listed with it, as metadata (never the contents).
attachments[].idRequiredstring (uuid)
attachments[].fileNameRequiredstring
attachments[].contentTypeRequiredstringOne of image/jpeg, image/png, image/webp, image/heic, application/pdf.
attachments[].sizeBytesRequiredinteger
createdAtRequiredstring (date-time)
answerIdRequiredstring (uuid)
sourcesRequiredarray of objectsWhere the answer came from. Show them.
sources[].titleRequiredstring
sources[].urlRequiredstring (uri) or null
actionsRequiredarray of objectsAt most a Book button, with an https address on the clinic's site. Never a contact button for a signed-in patient.
actions[].kindRequiredstringOne of book.
actions[].urlRequiredstring (uri)
actions[].labelstringOne of demo, appointment, consultation, call.
choicesRequiredarray of objectsThe buttons under the answer: send the id as choiceId.
choices[].idRequiredstringOne of helpful, talk_to_team.
choices[].labelRequiredstring

messages[] with type undefined

FieldTypeDescription
idRequiredstring (uuid)For the patient's own message, the requestId they sent.
sequenceRequiredintegerPosition in the conversation: 1, 2, 3 with no gaps. Order by this.At least 1.
kindRequiredstringOne of text, answer, question, review, emergency, handoff, notice, orders, closed.
fromRequiredobject
from.kindRequiredstringnezer 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.One of patient, nezer, care_team, system.
from.labelRequiredstringThe words to show: "You", "NezerCare", "Care team" (Spanish "Usted", "NezerCare", "Equipo médico"). Staff names are never sent.
priorityRequiredstringOne of normal, emergency.
languageRequiredstringThe language of text.One of en, es.
textRequiredstringAlways present: the words to show. A portal that renders nothing else can print text and stay correct. Never rewrite it.
causedByRequestIdstring (uuid)The patient request this message answers, when it answers one.
attachmentsarray of objectsOn a patient's message: the files they listed with it, as metadata (never the contents).
attachments[].idRequiredstring (uuid)
attachments[].fileNameRequiredstring
attachments[].contentTypeRequiredstringOne of image/jpeg, image/png, image/webp, image/heic, application/pdf.
attachments[].sizeBytesRequiredinteger
createdAtRequiredstring (date-time)
purposeRequiredstringOne of safety_check, intake, team_chat, workflow.
inputRequiredobjectchoice: pick one of choices. text: answer in words (up to maxLength). attachments: add photos with the attachments call, then press done (or skip).
input.typeRequiredstringOne of choice, text, attachments.
input.maxLengthintegerExample: 2000.
input.choicesarray of objects
input.choices[].idRequiredstringSend it as choiceId.One of helpful, talk_to_team, yes, no, unsure, send, send_now, done, skip.
input.choices[].labelRequiredstringThe words on the button, in the message's language.
choicesarray of objectsShortcuts beside the question: send_now ("Send to my care team now", for an urgent concern, at any point) or done and skip for photos.
choices[].idRequiredstringSend it as choiceId.One of helpful, talk_to_team, yes, no, unsure, send, send_now, done, skip.
choices[].labelRequiredstringThe words on the button, in the message's language.

messages[] with type undefined

FieldTypeDescription
idRequiredstring (uuid)For the patient's own message, the requestId they sent.
sequenceRequiredintegerPosition in the conversation: 1, 2, 3 with no gaps. Order by this.At least 1.
kindRequiredstringOne of text, answer, question, review, emergency, handoff, notice, orders, closed.
fromRequiredobject
from.kindRequiredstringnezer 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.One of patient, nezer, care_team, system.
from.labelRequiredstringThe words to show: "You", "NezerCare", "Care team" (Spanish "Usted", "NezerCare", "Equipo médico"). Staff names are never sent.
priorityRequiredstringOne of normal, emergency.
languageRequiredstringThe language of text.One of en, es.
textRequiredstringAlways present: the words to show. A portal that renders nothing else can print text and stay correct. Never rewrite it.
causedByRequestIdstring (uuid)The patient request this message answers, when it answers one.
attachmentsarray of objectsOn a patient's message: the files they listed with it, as metadata (never the contents).
attachments[].idRequiredstring (uuid)
attachments[].fileNameRequiredstring
attachments[].contentTypeRequiredstringOne of image/jpeg, image/png, image/webp, image/heic, application/pdf.
attachments[].sizeBytesRequiredinteger
createdAtRequiredstring (date-time)
statusRequiredstringOne of ready, urgent.
summaryRequiredstring
choicesRequiredarray of objects
choices[].idRequiredstringSend it as choiceId.One of helpful, talk_to_team, yes, no, unsure, send, send_now, done, skip.
choices[].labelRequiredstringThe words on the button, in the message's language.
inputRequiredobject
input.typestringOne of text.
input.maxLengthinteger
input.hintstringExample: Need to change something?.

messages[] with type undefined

FieldTypeDescription
idRequiredstring (uuid)For the patient's own message, the requestId they sent.
sequenceRequiredintegerPosition in the conversation: 1, 2, 3 with no gaps. Order by this.At least 1.
kindRequiredstringOne of text, answer, question, review, emergency, handoff, notice, orders, closed.
fromRequiredobject
from.kindRequiredstringnezer 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.One of patient, nezer, care_team, system.
from.labelRequiredstringThe words to show: "You", "NezerCare", "Care team" (Spanish "Usted", "NezerCare", "Equipo médico"). Staff names are never sent.
priorityRequiredstringOne of normal, emergency.
languageRequiredstringThe language of text.One of en, es.
textRequiredstringAlways present: the words to show. A portal that renders nothing else can print text and stay correct. Never rewrite it.
causedByRequestIdstring (uuid)The patient request this message answers, when it answers one.
attachmentsarray of objectsOn a patient's message: the files they listed with it, as metadata (never the contents).
attachments[].idRequiredstring (uuid)
attachments[].fileNameRequiredstring
attachments[].contentTypeRequiredstringOne of image/jpeg, image/png, image/webp, image/heic, application/pdf.
attachments[].sizeBytesRequiredinteger
createdAtRequiredstring (date-time)
ordersRequiredarray of objects
orders[].idRequiredstring
orders[].statusRequiredstringOne of processing, shipped, delivered, delayed, cancelled.
orders[].statusLabelstring or null
orders[].carrierstring or null
orders[].trackingUrlstring (uri) or null
orders[].estimatedDeliverystring or null
orders[].placedAtstring or null
orders[].itemsRequiredarray of objects
orders[].items[].nameRequiredstring
orders[].items[].quantityRequiredinteger

messages[] with type undefined

FieldTypeDescription
idRequiredstring (uuid)For the patient's own message, the requestId they sent.
sequenceRequiredintegerPosition in the conversation: 1, 2, 3 with no gaps. Order by this.At least 1.
kindRequiredstringOne of text, answer, question, review, emergency, handoff, notice, orders, closed.
fromRequiredobject
from.kindRequiredstringnezer 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.One of patient, nezer, care_team, system.
from.labelRequiredstringThe words to show: "You", "NezerCare", "Care team" (Spanish "Usted", "NezerCare", "Equipo médico"). Staff names are never sent.
priorityRequiredstringOne of normal, emergency.
languageRequiredstringThe language of text.One of en, es.
textRequiredstringAlways present: the words to show. A portal that renders nothing else can print text and stay correct. Never rewrite it.
causedByRequestIdstring (uuid)The patient request this message answers, when it answers one.
attachmentsarray of objectsOn a patient's message: the files they listed with it, as metadata (never the contents).
attachments[].idRequiredstring (uuid)
attachments[].fileNameRequiredstring
attachments[].contentTypeRequiredstringOne of image/jpeg, image/png, image/webp, image/heic, application/pdf.
attachments[].sizeBytesRequiredinteger
createdAtRequiredstring (date-time)
emergencyRequiredobject
emergency.linesRequiredarray of objectsThe ways to call. Thoughts of self-harm add 988.
emergency.lines[].labelRequiredstringExample: Call 911.
emergency.lines[].telRequiredstringExample: tel:911.
emergency.sentToCareTeamRequiredbooleanWhether 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.

messages[] with type undefined

FieldTypeDescription
idRequiredstring (uuid)For the patient's own message, the requestId they sent.
sequenceRequiredintegerPosition in the conversation: 1, 2, 3 with no gaps. Order by this.At least 1.
kindRequiredstringOne of text, answer, question, review, emergency, handoff, notice, orders, closed.
fromRequiredobject
from.kindRequiredstringnezer 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.One of patient, nezer, care_team, system.
from.labelRequiredstringThe words to show: "You", "NezerCare", "Care team" (Spanish "Usted", "NezerCare", "Equipo médico"). Staff names are never sent.
priorityRequiredstringOne of normal, emergency.
languageRequiredstringThe language of text.One of en, es.
textRequiredstringAlways present: the words to show. A portal that renders nothing else can print text and stay correct. Never rewrite it.
causedByRequestIdstring (uuid)The patient request this message answers, when it answers one.
attachmentsarray of objectsOn a patient's message: the files they listed with it, as metadata (never the contents).
attachments[].idRequiredstring (uuid)
attachments[].fileNameRequiredstring
attachments[].contentTypeRequiredstringOne of image/jpeg, image/png, image/webp, image/heic, application/pdf.
attachments[].sizeBytesRequiredinteger
createdAtRequiredstring (date-time)
handoffRequiredobject
handoff.referenceRequiredstringSomething the patient and the team can both quote.Matches ^NC-[0-9A-F]{8}$.
handoff.teamRequiredstringOne of clinical, billing, scheduling, fulfillment, support.
handoff.urgencyRequiredstringOne of routine, urgent.

messages[] with type undefined

FieldTypeDescription
idRequiredstring (uuid)For the patient's own message, the requestId they sent.
sequenceRequiredintegerPosition in the conversation: 1, 2, 3 with no gaps. Order by this.At least 1.
kindRequiredstringOne of text, answer, question, review, emergency, handoff, notice, orders, closed.
fromRequiredobject
from.kindRequiredstringnezer 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.One of patient, nezer, care_team, system.
from.labelRequiredstringThe words to show: "You", "NezerCare", "Care team" (Spanish "Usted", "NezerCare", "Equipo médico"). Staff names are never sent.
priorityRequiredstringOne of normal, emergency.
languageRequiredstringThe language of text.One of en, es.
textRequiredstringAlways present: the words to show. A portal that renders nothing else can print text and stay correct. Never rewrite it.
causedByRequestIdstring (uuid)The patient request this message answers, when it answers one.
attachmentsarray of objectsOn a patient's message: the files they listed with it, as metadata (never the contents).
attachments[].idRequiredstring (uuid)
attachments[].fileNameRequiredstring
attachments[].contentTypeRequiredstringOne of image/jpeg, image/png, image/webp, image/heic, application/pdf.
attachments[].sizeBytesRequiredinteger
createdAtRequiredstring (date-time)
noticeRequiredobject
notice.codeRequiredstringOne of paused.

messages[] with type undefined

FieldTypeDescription
idRequiredstring (uuid)For the patient's own message, the requestId they sent.
sequenceRequiredintegerPosition in the conversation: 1, 2, 3 with no gaps. Order by this.At least 1.
kindRequiredstringOne of text, answer, question, review, emergency, handoff, notice, orders, closed.
fromRequiredobject
from.kindRequiredstringnezer 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.One of patient, nezer, care_team, system.
from.labelRequiredstringThe words to show: "You", "NezerCare", "Care team" (Spanish "Usted", "NezerCare", "Equipo médico"). Staff names are never sent.
priorityRequiredstringOne of normal, emergency.
languageRequiredstringThe language of text.One of en, es.
textRequiredstringAlways present: the words to show. A portal that renders nothing else can print text and stay correct. Never rewrite it.
causedByRequestIdstring (uuid)The patient request this message answers, when it answers one.
attachmentsarray of objectsOn a patient's message: the files they listed with it, as metadata (never the contents).
attachments[].idRequiredstring (uuid)
attachments[].fileNameRequiredstring
attachments[].contentTypeRequiredstringOne of image/jpeg, image/png, image/webp, image/heic, application/pdf.
attachments[].sizeBytesRequiredinteger
createdAtRequiredstring (date-time)
closedRequiredobject
closed.reasonRequiredstringOne of closed.
FieldTypeDescription
scheduledForRequiredstring (date-time)The start, in UTC (show it in the patient's own time zone).
visitUrlstring (uri) or nullThe link to join the visit; null for an appointment booked before links were required; absent in a webhook.
200: A care team reply
{
  "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"
  }
}
200: The conversation closed
{
  "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 response
{
  "code": "INVALID_REQUEST",
  "message": "afterSequence must not be less than 0"
}
401 response
{
  "code": "INVALID_API_CREDENTIAL",
  "message": "API credential is invalid."
}
403 response
{
  "code": "INSUFFICIENT_SCOPE",
  "message": "This API key doesn't have the portal_messaging scope. Create a key with it in Integrations, API keys."
}
404 response
{
  "code": "CONVERSATION_NOT_FOUND",
  "message": "No conversation with this ID for this patient."
}
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."
}