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.

Read an ordered conversation

GET/v1/conversations/{conversationId}/messages

API key. Authorization: Bearer nzh_sb_… in sandbox, nzh_prod_… in production: Authentication.

Parameters

Field	Type	Description
`conversationId`Required	path · string (uuid)
`afterSequence`	query · integer	At least 0.Defaults to `0`.

cURL

curl "https://api.nezercare.com/v1/conversations/CONVERSATION_ID/messages?afterSequence=0" \
  --request GET \
  --header "Authorization: Bearer $NEZER_API_KEY"

Responses

Status	Meaning
`200`	Messages ordered by ascending sequence.
`400`	The request is malformed or violates the operation contract.
`401`	The API credential is missing, invalid, expired, or revoked.
`403`	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 at once.
`404`	The resource is not accessible in this credential's environment.
`409`	The idempotency identifier was reused with different content, or an update is out of sequence.

401 response

{
  "code": "INVALID_API_CREDENTIAL",
  "message": "API credential is invalid."
}

403 response

{
  "code": "BAA_REQUIRED",
  "message": "Sign your BAA to turn on patient features. An owner or administrator can sign it in Settings."
}

Send an inbound external message

POST/v1/conversations/{conversationId}/messages

API key. Authorization: Bearer nzh_sb_… in sandbox, nzh_prod_… in production: Authentication.

Parameters

Field	Type	Description
`conversationId`Required	path · string (uuid)

Request body

Field	Type	Description
`requestId`Required	string (uuid)
`message`Required	string	1–10000 characters.
`externalMessageId`	string	Up to 200 characters.
`attachments`	array of objects
`attachments[].id`Required	string (uuid)
`attachments[].fileName`Required	string	Up to 200 characters.
`attachments[].contentType`Required	string	Up to 160 characters.
`attachments[].sha256`Required	string	Matches `^[a-f0-9]{64}$`.

Responses

Status	Meaning
`201`	Message created or identical retry recognized.
`400`	The request is malformed or violates the operation contract.
`401`	The API credential is missing, invalid, expired, or revoked.
`403`	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 at once.
`404`	The resource is not accessible in this credential's environment.
`409`	The idempotency identifier was reused with different content, or an update is out of sequence.

401 response

{
  "code": "INVALID_API_CREDENTIAL",
  "message": "API credential is invalid."
}

403 response

{
  "code": "BAA_REQUIRED",
  "message": "Sign your BAA to turn on patient features. An owner or administrator can sign it in Settings."
}

Report external delivery state

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

API key. Authorization: Bearer nzh_sb_… in sandbox, nzh_prod_… in production: Authentication.

Parameters

Field	Type	Description
`conversationId`Required	path · string (uuid)
`messageId`Required	path · string (uuid)

Request body

Field	Type	Description
`externalMessageId`Required	string	Up to 200 characters.
`status`Required	string	One of `delivered`, `read`, `failed`.
`errorCode`	string	Up to 80 characters.

Responses

Status	Meaning
`201`	Delivery state recorded.
`400`	The request is malformed or violates the operation contract.
`401`	The API credential is missing, invalid, expired, or revoked.
`403`	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 at once.
`404`	The resource is not accessible in this credential's environment.
`409`	The idempotency identifier was reused with different content, or an update is out of sequence.

401 response

{
  "code": "INVALID_API_CREDENTIAL",
  "message": "API credential is invalid."
}

403 response

{
  "code": "BAA_REQUIRED",
  "message": "Sign your BAA to turn on patient features. An owner or administrator can sign it in Settings."
}