Case comments

This API allows you to add a new comment, such as a text message with optional attachment, to an existing case, add an internal note to an existing case, tag case assignees, etc.

HTTP Request

POST <BASE_URL>/api/v1/cases/:caseId

Parameter	Type	Description
caseId	string	Required. The unique identifier (UUID) of the case.

Headers

Header	Type	Description
cv-api-key	string	Required. Your unique API key for authentication.
Content-Type	string	Required. Must be application/json.

Request Body

The request body is a JSON object with a top-level action field and a communication object containing the details of the message and any attachments.

Field	Type	Description
action	string	Required. The action to be performed. This must be ADD_COMMUNICATION.
communication	object	An object containing the communication details.

communication Object

Field	Type	Description
text	string	The message to be added to the case.
isRestricted	boolean	Indicates if the communication should be restricted. False by default.
author	object	An object containing the author's details.
attachments	array of objects	An array of attachment objects. (Optional)

author Object

Field	Type	Description
email	string	The author's email address (Required).
firstName	string	The author's first name.
lastName	string	The author's last name.

attachments Object

Field	Type	Description
isRestricted	boolean	Indicates if the attachment should be restricted.
isPHI	boolean	Indicates if the attachment contains Protected Health Information.
fileName	string	The file name of the attachment (e.g., document.pdf).
content	string	The file content encoded as a Base64 string.

Example Request

curl --location '<BASE_URL>/api/v1/cases/:caseId' \
--header 'cv-api-key: <redacted>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "action": "ADD_COMMUNICATION",
    "communication": {
        "text": "Comment text",
        "isRestricted": false,
        "author": {
            "email": "support_user@carevalidate.com",
            "firstName": "John",
            "lastName": "Doe"
        },
        "attachments": [
        {
            "isRestricted": false,
            "isPHI": false,
            "fileName": "Screenshot_01.png",
            "content": "BASE64_STRING"
        }]
    }
}

---

Responses

Success Response

A successful request returns a 200 status code with a message confirming the comment was created and includes the comment's unique ID and creation timestamp.

{
  "status": 200,
  "success": true,
  "message": "Case comment created successfully",
  "data": {
    "commentId": "e4f8d5a2-9b2f-4c5c-8d1f-8c6f1d9e2a3b",
    "createdAt": "2024-09-04T12:00:00.000Z"
  }
}

Failure Responses

A request can fail for several reasons, returning a 400 Bad Request or a specific error message.

Invalid action in the request body:

If the action field is not a recognized value like ADD_COMMUNICATION, the API will return a bad request error.

{
  "status": 400,
  "success": false,
  "message": "Invalid request",
  "error": "Invalid action"
}

Invalid request:

Any other validation or processing error will result in a generic invalid request error.

{
  "status": 400,
  "success": false,
  "message": "Invalid request",
  "error": "Specific error message here"
}

Missing required fields

If any of the required fields (text, isRestricted, or author) are missing from the communication object, the API will return a specific error message.

{
  "status": 400,
  "success": false,
  "message": "Invalid request",
  "error": "Missing required field `text`"
}

{
  "status": 400,
  "success": false,
  "message": "Invalid request",
  "error": "Missing required field `isRestricted`"
}

{
  "status": 400,
  "success": false,
  "message": "Invalid request",
  "error": "Missing required field `author`"
}

Case Not Found

This response is returned if no case exists with the provided caseId.

{
  "status": 404,
  "success": false,
  "message": "Invalid request",
  "error": "No Case found for provided details!"
}

Permission Denied

This response occurs if the case exists but belongs to a different organization, indicating that the cv-api-key does not have permission to access it.

{
  "status": 403,
  "success": false,
  "message": "Invalid request",
  "error": "Permission denied!"
}

Invalid tagged user

If the attachments array contains a user object that is missing the required email field, the API will return a 400 Bad Request error.

{
  "status": 400,
  "success": false,
  "message": "Invalid request",
  "error": "`email` field is required for tagged users"
}

Missing attachment fields

If an attachment object is missing the content or fileName field, the API will return a 400 Bad Request error.

{
  "status": 400,
  "success": false,
  "message": "Invalid request",
  "error": "`content` field is required for attachments"
}

{
  "status": 400,
  "success": false,
  "message": "Invalid request",
  "error": "`fileName` field is required for attachments"
}