Skip to content

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/v1/conversations/{conversationId}/messages

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

FieldTypeDescription
conversationIdRequiredpath · 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.
afterSequencequery · integerOnly messages after this sequence number; 0 reads from the start.At least 0.Defaults to 0.
includeInternalquery · booleantrue 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
curl "https://api.nezercare.com/v1/conversations/CONVERSATION_ID/messages?afterSequence=0&includeInternal=false" \
  --request GET \
  --header "Authorization: Bearer $NEZER_API_KEY"

Responses

StatusMeaning
200Messages ordered by ascending sequence: patient-visible only, or every message with includeInternal=true. A plain JSON array, empty when there is nothing after afterSequence.
400The request is malformed or breaks the operation's contract: a field of the wrong type or outside its limits, a field the operation doesn't take (unknown fields are refused, not ignored), or an ID that isn't a UUID. message is a sentence, or a list of sentences, one for each field that failed.
401MISSING_API_CREDENTIAL: no bearer key was sent. INVALID_API_CREDENTIAL: the key is invalid, expired, or revoked.
403BAA_REQUIRED: the organization hasn't signed its BAA, so patient features (and API keys) are off. An owner or administrator signs it in Settings; it takes effect within about half a minute. INSUFFICIENT_SCOPE: the key wasn't made for this route (see the scope in the operation's description); make a new key with the scope, as a key never gains one later.
404No 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.
409A 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.
429RATE_LIMITED: this API key has sent more requests than it may on all the routes it can call together (the clinical-case routes, the conversation gateway and Patient messaging): 600 a minute and 20,000 an hour. Nothing is read, written or audited by a refused call. Honor Retry-After (seconds), then retry with the same identifiers.
200 response
[
  {
    "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"
  }
]
400 response
{
  "message": [
    "message must be shorter than or equal to 10000 characters"
  ],
  "error": "Bad Request",
  "statusCode": 400
}
401: No key sent
{
  "code": "MISSING_API_CREDENTIAL",
  "message": "A bearer API credential is required."
}
401: Invalid, expired or revoked key
{
  "code": "INVALID_API_CREDENTIAL",
  "message": "API credential is invalid."
}
403: BAA not signed
{
  "code": "BAA_REQUIRED",
  "message": "Sign your BAA to turn on patient features. An owner or administrator can sign it in Settings."
}
403: The key lacks the scope
{
  "code": "INSUFFICIENT_SCOPE",
  "message": "This API key doesn't have the conversation_gateway scope. Create a key with it in Integrations, API keys."
}
404 response
{
  "message": "Conversation not found.",
  "error": "Not Found",
  "statusCode": 404
}
409: An ID reused with different content
{
  "message": "This requestId was already used with different content.",
  "error": "Conflict",
  "statusCode": 409
}
409: A message to a closed conversation
{
  "message": "Conversation is closed.",
  "error": "Conflict",
  "statusCode": 409
}
409: A key of a retired workspace
{
  "code": "ENVIRONMENT_RETIRED",
  "message": "This API key belongs to an earlier copy of your organization's workspace, which was retired. Create a new key in your workspace (Integrations, API keys) and use it instead."
}
429 response
{
  "code": "RATE_LIMITED",
  "message": "This API key is sending requests faster than allowed (600 a minute). Wait for Retry-After, then retry with the same requestId."
}

Send a message from your system

POST/v1/conversations/{conversationId}/messages

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

FieldTypeDescription
conversationIdRequiredpath · 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

FieldTypeDescription
requestIdRequiredstring (uuid)Generated by you, once for each message; it becomes the message's id.
messageRequiredstringPatient-visible: write nothing in it that a patient shouldn't read.1–10000 characters.
externalMessageIdstringYour own ID for the message, kept with it.1–200 characters.
attachmentsarray of objectsRecords of files you hold. NezerCare stores these details and no file.
attachments[].idRequiredstring (uuid)
attachments[].fileNameRequiredstring1–200 characters.
attachments[].contentTypeRequiredstringUp to 160 characters.Example: application/pdf.
attachments[].sha256RequiredstringThe SHA-256 of the file's bytes, in lowercase hex.Matches ^[a-f0-9]{64}$.

Responses

StatusMeaning
201Message created, or an identical retry recognized (duplicate: true).
400The request is malformed or breaks the operation's contract: a field of the wrong type or outside its limits, a field the operation doesn't take (unknown fields are refused, not ignored), or an ID that isn't a UUID. message is a sentence, or a list of sentences, one for each field that failed.
401MISSING_API_CREDENTIAL: no bearer key was sent. INVALID_API_CREDENTIAL: the key is invalid, expired, or revoked.
403BAA_REQUIRED: the organization hasn't signed its BAA, so patient features (and API keys) are off. An owner or administrator signs it in Settings; it takes effect within about half a minute. INSUFFICIENT_SCOPE: the key wasn't made for this route (see the scope in the operation's description); make a new key with the scope, as a key never gains one later.
404No 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.
409A 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.
429RATE_LIMITED: this API key has sent more requests than it may on all the routes it can call together (the clinical-case routes, the conversation gateway and Patient messaging): 600 a minute and 20,000 an hour. Nothing is read, written or audited by a refused call. Honor Retry-After (seconds), then retry with the same identifiers.

201 body

FieldTypeDescription
conversationIdRequiredstring (uuid)
messageIdRequiredstring (uuid)The requestId you sent.
sequenceRequiredintegerAt least 1.
duplicateRequiredbooleanTrue when this is the stored result of a requestId already handled.
createdAtRequiredstring (date-time)
201 response
{
  "conversationId": "ec768b8c-acad-49df-8c8e-438494dd320a",
  "messageId": "55555555-2222-4333-8444-555555555555",
  "sequence": 4,
  "duplicate": false,
  "createdAt": "2026-10-21T04:29:06.691Z"
}
400 response
{
  "message": [
    "message must be shorter than or equal to 10000 characters"
  ],
  "error": "Bad Request",
  "statusCode": 400
}
401: No key sent
{
  "code": "MISSING_API_CREDENTIAL",
  "message": "A bearer API credential is required."
}
401: Invalid, expired or revoked key
{
  "code": "INVALID_API_CREDENTIAL",
  "message": "API credential is invalid."
}
403: BAA not signed
{
  "code": "BAA_REQUIRED",
  "message": "Sign your BAA to turn on patient features. An owner or administrator can sign it in Settings."
}
403: The key lacks the scope
{
  "code": "INSUFFICIENT_SCOPE",
  "message": "This API key doesn't have the conversation_gateway scope. Create a key with it in Integrations, API keys."
}
404 response
{
  "message": "Conversation not found.",
  "error": "Not Found",
  "statusCode": 404
}
409: An ID reused with different content
{
  "message": "This requestId was already used with different content.",
  "error": "Conflict",
  "statusCode": 409
}
409: A message to a closed conversation
{
  "message": "Conversation is closed.",
  "error": "Conflict",
  "statusCode": 409
}
409: A key of a retired workspace
{
  "code": "ENVIRONMENT_RETIRED",
  "message": "This API key belongs to an earlier copy of your organization's workspace, which was retired. Create a new key in your workspace (Integrations, API keys) and use it instead."
}
429 response
{
  "code": "RATE_LIMITED",
  "message": "This API key is sending requests faster than allowed (600 a minute). Wait for Retry-After, then retry with the same requestId."
}

Report external delivery state

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

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

FieldTypeDescription
conversationIdRequiredpath · 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.
messageIdRequiredpath · string (uuid)The ID of the message the receipt is for (its id in the thread).

Request body

FieldTypeDescription
externalMessageIdRequiredstringYour own ID for your copy of the message.1–200 characters.
statusRequiredstringOne of delivered, read, failed.
errorCodestringA short machine word for why it failed. Never anyone's words.1–80 characters.

Responses

StatusMeaning
201Delivery 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.
400The request is malformed or breaks the operation's contract: a field of the wrong type or outside its limits, a field the operation doesn't take (unknown fields are refused, not ignored), or an ID that isn't a UUID. message is a sentence, or a list of sentences, one for each field that failed.
401MISSING_API_CREDENTIAL: no bearer key was sent. INVALID_API_CREDENTIAL: the key is invalid, expired, or revoked.
403BAA_REQUIRED: the organization hasn't signed its BAA, so patient features (and API keys) are off. An owner or administrator signs it in Settings; it takes effect within about half a minute. INSUFFICIENT_SCOPE: the key wasn't made for this route (see the scope in the operation's description); make a new key with the scope, as a key never gains one later.
404No 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.
409A 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.
429RATE_LIMITED: this API key has sent more requests than it may on all the routes it can call together (the clinical-case routes, the conversation gateway and Patient messaging): 600 a minute and 20,000 an hour. Nothing is read, written or audited by a refused call. Honor Retry-After (seconds), then retry with the same identifiers.

201 body

FieldTypeDescription
conversationIdRequiredstring (uuid)
messageIdRequiredstring (uuid)
statusRequiredstringOne of delivered, read, failed.
updatedAtRequiredstring (date-time)
201 response
{
  "conversationId": "ec768b8c-acad-49df-8c8e-438494dd320a",
  "messageId": "b7ad7856-5ab6-4fea-b978-e174ec033350",
  "status": "delivered",
  "updatedAt": "2026-10-21T04:30:22.621Z"
}
400 response
{
  "message": [
    "message must be shorter than or equal to 10000 characters"
  ],
  "error": "Bad Request",
  "statusCode": 400
}
401: No key sent
{
  "code": "MISSING_API_CREDENTIAL",
  "message": "A bearer API credential is required."
}
401: Invalid, expired or revoked key
{
  "code": "INVALID_API_CREDENTIAL",
  "message": "API credential is invalid."
}
403: BAA not signed
{
  "code": "BAA_REQUIRED",
  "message": "Sign your BAA to turn on patient features. An owner or administrator can sign it in Settings."
}
403: The key lacks the scope
{
  "code": "INSUFFICIENT_SCOPE",
  "message": "This API key doesn't have the conversation_gateway scope. Create a key with it in Integrations, API keys."
}
404 response
{
  "message": "Conversation not found.",
  "error": "Not Found",
  "statusCode": 404
}
409: An ID reused with different content
{
  "message": "This requestId was already used with different content.",
  "error": "Conflict",
  "statusCode": 409
}
409: A message to a closed conversation
{
  "message": "Conversation is closed.",
  "error": "Conflict",
  "statusCode": 409
}
409: A key of a retired workspace
{
  "code": "ENVIRONMENT_RETIRED",
  "message": "This API key belongs to an earlier copy of your organization's workspace, which was retired. Create a new key in your workspace (Integrations, API keys) and use it instead."
}
429 response
{
  "code": "RATE_LIMITED",
  "message": "This API key is sending requests faster than allowed (600 a minute). Wait for Retry-After, then retry with the same requestId."
}