API reference
Conversations
Read and send messages in a case's thread.
One ordered message thread for a clinical case or work item. Read messages after a sequence number, send a message from your system with a caller-generated requestId, and report delivery (delivered, read or failed). A conversation only carries messages: it can't resolve a case or make a care decision. The routes work on a conversation whose ID you already have: this API has no call that lists conversations or finds one, and no webhook announces them. A patient portal doesn't use these routes: it uses Patient messaging, which has its own conversations, runs the emergency check on every message and never returns an internal note.
Read an ordered conversation
GET/
Needs a key with the conversation_gateway scope. The thread as the patient sees it, in order, for a conversation of any category. Staff-only internal notes (a hand-off summary, a note the team wrote) are left out unless includeInternal=true, which also needs the conversation_internal_notes scope (403 INSUFFICIENT_SCOPE without it; only an owner or administrator can give a key that scope, and no key made before it existed has it); then every message in the answer has a visibility, patient or internal (it is on each message either way). Any includeInternal value but true reads as false. Internal notes are for your own staff tools: never show them to a patient. The answer is a plain JSON array of up to 250 messages after afterSequence; when 250 come back, ask again with the last sequence. Each read that returns a message is recorded in the workspace's audit log with the key and the conversation, never the messages. This is not what a patient portal reads: a portal uses Patient messaging.
API key. Authorization: Bearer nzh_prod_… (or a key made earlier, nzh_sb_…): Authentication.
Parameters
| Field | Type | Description |
|---|---|---|
conversationIdRequired | path · string (uuid) | The conversation's ID in NezerCare. This API has no call that lists conversations or finds one, and no webhook announces them. It isn't a clinical case's caseId and isn't the conversationId of Patient messaging, which names a portal conversation of its own. |
afterSequence | query · integer | Only messages after this sequence number; 0 reads from the start.At least 0.Defaults to 0. |
includeInternal | query · boolean | true adds the team's internal notes, marked visibility: "internal"; needs the conversation_internal_notes scope. Leave it out for anything a patient sees. Any other value reads as false.Defaults to false. |
curl "https://api.nezercare.com/v1/conversations/CONVERSATION_ID/messages?afterSequence=0&includeInternal=false" \
--request GET \
--header "Authorization: Bearer $NEZER_API_KEY"Responses
| Status | Meaning |
|---|---|
200 | Messages ordered by ascending sequence: patient-visible only, or every message with includeInternal=true. A plain JSON array, empty when there is nothing after afterSequence. |
400 | The request is malformed or breaks the operation's contract: a field of the wrong type or outside its limits, a field the operation doesn't take (unknown fields are refused, not ignored), or an ID that isn't a UUID. message is a sentence, or a list of sentences, one for each field that failed. |
401 | MISSING_API_CREDENTIAL: no bearer key was sent. INVALID_API_CREDENTIAL: the key is invalid, expired, or revoked. |
403 | BAA_REQUIRED: the organization hasn't signed its BAA, so patient features (and API keys) are off. An owner or administrator signs it in Settings; it takes effect within about half a minute. INSUFFICIENT_SCOPE: the key wasn't made for this route (see the scope in the operation's description); make a new key with the scope, as a key never gains one later. |
404 | No conversation with this ID in the key's organization, or (on the delivery receipt) no message of it that NezerCare queued for your system. Another organization's looks the same as one that never existed. |
409 | A conflict; the body says which. A requestId reused with different content, or a message to a closed conversation. Or (code ENVIRONMENT_RETIRED) the API key belongs to an earlier copy of the organization's workspace that was retired in October 2026: every request with it is refused; create a new key in the workspace. |
429 | RATE_LIMITED: this API key has sent more requests than it may on all the routes it can call together (the clinical-case routes, the conversation gateway and Patient messaging): 600 a minute and 20,000 an hour. Nothing is read, written or audited by a refused call. Honor Retry-After (seconds), then retry with the same identifiers. |
[
{
"id": "620e855b-cb3d-4823-9260-1b8935693e38",
"organizationId": "6b1f2c3d-4e5f-4a6b-8c7d-0e1f2a3b4c5d",
"environmentId": "1d2c3b4a-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"conversationId": "ec768b8c-acad-49df-8c8e-438494dd320a",
"sequence": 1,
"senderType": "patient",
"senderId": "2c3d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f",
"direction": "inbound",
"requestHash": "b8ec3ec479f2bc3e52653b57bd56c35955d592162d3f6e61e33eeb04c78505e1",
"externalMessageId": null,
"createdAt": "2026-10-21T04:28:23.042Z",
"visibility": "patient",
"attachments": [],
"message": "I was charged twice for my last order"
}
]{
"message": [
"message must be shorter than or equal to 10000 characters"
],
"error": "Bad Request",
"statusCode": 400
}{
"code": "MISSING_API_CREDENTIAL",
"message": "A bearer API credential is required."
}{
"code": "INVALID_API_CREDENTIAL",
"message": "API credential is invalid."
}{
"code": "BAA_REQUIRED",
"message": "Sign your BAA to turn on patient features. An owner or administrator can sign it in Settings."
}{
"code": "INSUFFICIENT_SCOPE",
"message": "This API key doesn't have the conversation_gateway scope. Create a key with it in Integrations, API keys."
}{
"message": "Conversation not found.",
"error": "Not Found",
"statusCode": 404
}{
"message": "This requestId was already used with different content.",
"error": "Conflict",
"statusCode": 409
}{
"message": "Conversation is closed.",
"error": "Conflict",
"statusCode": 409
}{
"code": "ENVIRONMENT_RETIRED",
"message": "This API key belongs to an earlier copy of your organization's workspace, which was retired. Create a new key in your workspace (Integrations, API keys) and use it instead."
}{
"code": "RATE_LIMITED",
"message": "This API key is sending requests faster than allowed (600 a minute). Wait for Retry-After, then retry with the same requestId."
}Send a message from your system
POST/
Needs a key with the conversation_gateway scope. Adds a message from your system to the conversation: stored as senderType: external, direction: inbound and patient-visible. NezerCare does not route it, answer it or run the emergency check on it, and it doesn't email the patient, so this is not how a patient's words reach NezerCare (a patient portal uses Patient messaging for that). In a conversation that a patient portal also shows, the message appears in the portal's feed as a message from the care team. attachments are records of files you hold (a name, a type and a SHA-256); this API stores no file and has no upload or download call. 409 when the conversation is closed. A retry with the same requestId and the same words is 201 with duplicate: true; the same requestId with other words is 409.
API key. Authorization: Bearer nzh_prod_… (or a key made earlier, nzh_sb_…): Authentication.
Parameters
| Field | Type | Description |
|---|---|---|
conversationIdRequired | path · string (uuid) | The conversation's ID in NezerCare. This API has no call that lists conversations or finds one, and no webhook announces them. It isn't a clinical case's caseId and isn't the conversationId of Patient messaging, which names a portal conversation of its own. |
Request body
| Field | Type | Description |
|---|---|---|
requestIdRequired | string (uuid) | Generated by you, once for each message; it becomes the message's id. |
messageRequired | string | Patient-visible: write nothing in it that a patient shouldn't read.1–10000 characters. |
externalMessageId | string | Your own ID for the message, kept with it.1–200 characters. |
attachments | array of objects | Records of files you hold. NezerCare stores these details and no file. |
attachments[].Required | string (uuid) | |
attachments[].Required | string | 1–200 characters. |
attachments[].Required | string | Up to 160 characters.Example: application/pdf. |
attachments[].Required | string | The SHA-256 of the file's bytes, in lowercase hex.Matches ^[a-f0-9]{64}$. |
Responses
| Status | Meaning |
|---|---|
201 | Message created, or an identical retry recognized (duplicate: true). |
400 | The request is malformed or breaks the operation's contract: a field of the wrong type or outside its limits, a field the operation doesn't take (unknown fields are refused, not ignored), or an ID that isn't a UUID. message is a sentence, or a list of sentences, one for each field that failed. |
401 | MISSING_API_CREDENTIAL: no bearer key was sent. INVALID_API_CREDENTIAL: the key is invalid, expired, or revoked. |
403 | BAA_REQUIRED: the organization hasn't signed its BAA, so patient features (and API keys) are off. An owner or administrator signs it in Settings; it takes effect within about half a minute. INSUFFICIENT_SCOPE: the key wasn't made for this route (see the scope in the operation's description); make a new key with the scope, as a key never gains one later. |
404 | No conversation with this ID in the key's organization, or (on the delivery receipt) no message of it that NezerCare queued for your system. Another organization's looks the same as one that never existed. |
409 | A conflict; the body says which. A requestId reused with different content, or a message to a closed conversation. Or (code ENVIRONMENT_RETIRED) the API key belongs to an earlier copy of the organization's workspace that was retired in October 2026: every request with it is refused; create a new key in the workspace. |
429 | RATE_LIMITED: this API key has sent more requests than it may on all the routes it can call together (the clinical-case routes, the conversation gateway and Patient messaging): 600 a minute and 20,000 an hour. Nothing is read, written or audited by a refused call. Honor Retry-After (seconds), then retry with the same identifiers. |
201 body
| Field | Type | Description |
|---|---|---|
conversationIdRequired | string (uuid) | |
messageIdRequired | string (uuid) | The requestId you sent. |
sequenceRequired | integer | At least 1. |
duplicateRequired | boolean | True when this is the stored result of a requestId already handled. |
createdAtRequired | string (date-time) |
{
"conversationId": "ec768b8c-acad-49df-8c8e-438494dd320a",
"messageId": "55555555-2222-4333-8444-555555555555",
"sequence": 4,
"duplicate": false,
"createdAt": "2026-10-21T04:29:06.691Z"
}{
"message": [
"message must be shorter than or equal to 10000 characters"
],
"error": "Bad Request",
"statusCode": 400
}{
"code": "MISSING_API_CREDENTIAL",
"message": "A bearer API credential is required."
}{
"code": "INVALID_API_CREDENTIAL",
"message": "API credential is invalid."
}{
"code": "BAA_REQUIRED",
"message": "Sign your BAA to turn on patient features. An owner or administrator can sign it in Settings."
}{
"code": "INSUFFICIENT_SCOPE",
"message": "This API key doesn't have the conversation_gateway scope. Create a key with it in Integrations, API keys."
}{
"message": "Conversation not found.",
"error": "Not Found",
"statusCode": 404
}{
"message": "This requestId was already used with different content.",
"error": "Conflict",
"statusCode": 409
}{
"message": "Conversation is closed.",
"error": "Conflict",
"statusCode": 409
}{
"code": "ENVIRONMENT_RETIRED",
"message": "This API key belongs to an earlier copy of your organization's workspace, which was retired. Create a new key in your workspace (Integrations, API keys) and use it instead."
}{
"code": "RATE_LIMITED",
"message": "This API key is sending requests faster than allowed (600 a minute). Wait for Retry-After, then retry with the same requestId."
}Report external delivery state
POST/
Needs a key with the conversation_gateway scope. A receipt is only taken for a message NezerCare queued for your system to pass on to the patient: an outbound, patient-visible message of your workspace. For a patient's own message, an internal note, a message of another conversation or another workspace, or an ID that doesn't exist, the answer is 404 and nothing is recorded.
API key. Authorization: Bearer nzh_prod_… (or a key made earlier, nzh_sb_…): Authentication.
Parameters
| Field | Type | Description |
|---|---|---|
conversationIdRequired | path · string (uuid) | The conversation's ID in NezerCare. This API has no call that lists conversations or finds one, and no webhook announces them. It isn't a clinical case's caseId and isn't the conversationId of Patient messaging, which names a portal conversation of its own. |
messageIdRequired | path · string (uuid) | The ID of the message the receipt is for (its id in the thread). |
Request body
| Field | Type | Description |
|---|---|---|
externalMessageIdRequired | string | Your own ID for your copy of the message.1–200 characters. |
statusRequired | string | One of delivered, read, failed. |
errorCode | string | A short machine word for why it failed. Never anyone's words.1–80 characters. |
Responses
| Status | Meaning |
|---|---|
201 | Delivery state recorded. A repeat of the same status for the same externalMessageId is answered the same way (201, with no duplicate flag) and is not recorded again. A failed receipt opens a high-priority work item for the care team. |
400 | The request is malformed or breaks the operation's contract: a field of the wrong type or outside its limits, a field the operation doesn't take (unknown fields are refused, not ignored), or an ID that isn't a UUID. message is a sentence, or a list of sentences, one for each field that failed. |
401 | MISSING_API_CREDENTIAL: no bearer key was sent. INVALID_API_CREDENTIAL: the key is invalid, expired, or revoked. |
403 | BAA_REQUIRED: the organization hasn't signed its BAA, so patient features (and API keys) are off. An owner or administrator signs it in Settings; it takes effect within about half a minute. INSUFFICIENT_SCOPE: the key wasn't made for this route (see the scope in the operation's description); make a new key with the scope, as a key never gains one later. |
404 | No conversation with this ID in the key's organization, or (on the delivery receipt) no message of it that NezerCare queued for your system. Another organization's looks the same as one that never existed. |
409 | A conflict; the body says which. A requestId reused with different content, or a message to a closed conversation. Or (code ENVIRONMENT_RETIRED) the API key belongs to an earlier copy of the organization's workspace that was retired in October 2026: every request with it is refused; create a new key in the workspace. |
429 | RATE_LIMITED: this API key has sent more requests than it may on all the routes it can call together (the clinical-case routes, the conversation gateway and Patient messaging): 600 a minute and 20,000 an hour. Nothing is read, written or audited by a refused call. Honor Retry-After (seconds), then retry with the same identifiers. |
201 body
| Field | Type | Description |
|---|---|---|
conversationIdRequired | string (uuid) | |
messageIdRequired | string (uuid) | |
statusRequired | string | One of delivered, read, failed. |
updatedAtRequired | string (date-time) |
{
"conversationId": "ec768b8c-acad-49df-8c8e-438494dd320a",
"messageId": "b7ad7856-5ab6-4fea-b978-e174ec033350",
"status": "delivered",
"updatedAt": "2026-10-21T04:30:22.621Z"
}{
"message": [
"message must be shorter than or equal to 10000 characters"
],
"error": "Bad Request",
"statusCode": 400
}{
"code": "MISSING_API_CREDENTIAL",
"message": "A bearer API credential is required."
}{
"code": "INVALID_API_CREDENTIAL",
"message": "API credential is invalid."
}{
"code": "BAA_REQUIRED",
"message": "Sign your BAA to turn on patient features. An owner or administrator can sign it in Settings."
}{
"code": "INSUFFICIENT_SCOPE",
"message": "This API key doesn't have the conversation_gateway scope. Create a key with it in Integrations, API keys."
}{
"message": "Conversation not found.",
"error": "Not Found",
"statusCode": 404
}{
"message": "This requestId was already used with different content.",
"error": "Conflict",
"statusCode": 409
}{
"message": "Conversation is closed.",
"error": "Conflict",
"statusCode": 409
}{
"code": "ENVIRONMENT_RETIRED",
"message": "This API key belongs to an earlier copy of your organization's workspace, which was retired. Create a new key in your workspace (Integrations, API keys) and use it instead."
}{
"code": "RATE_LIMITED",
"message": "This API key is sending requests faster than allowed (600 a minute). Wait for Retry-After, then retry with the same requestId."
}