Update Escalation

POST/api/v1/cases/:caseId

Updates one or more existing escalations on a case using the UPDATE_ESCALATION action.

cv-api-key

Productionhttps://api.care360-next.carevalidate.com/api/v1/cases/:caseId

Staginghttps://api-staging.care360-next.carevalidate.com/api/v1/cases/:caseId

Parameters

Path Parameters

caseIdstringrequired

The unique identifier (UUID) of the case.

Headers

cv-api-keystringrequired

Your unique API key for authentication.

Content-Typestringrequired

Must be application/json.

Example: application/json

Request Body

actionstringrequired

Action to perform. Must be `UPDATE_ESCALATION`.

Values:UPDATE_ESCALATION

escalationsarray of objectsrequired

One or more escalation updates. At least one item is required. All referenced escalations must belong to the specified case and must not be completed.

Show 4 child properties

escalationIdstringrequired

The UUID of the escalation to update.

notestringoptional

New note text to set on the escalation.

followUpDueAtstringoptional

ISO 8601 datetime for the follow-up due date (e.g. `2025-06-01T12:00:00.000Z`). Replaces the existing value.

assignedToEmailstringoptional

Email address of a TPA user to reassign the escalation to. The user must be a CVTPA account with access to this organization. Replaces the existing assignment.

Error Behaviour

When one or more escalationId values are not found among the case's active (non-completed) escalations, the endpoint returns a 400 response that includes the current list of active escalations in data.escalations. Use this list to identify valid IDs.

Examples

cURL

curl --location '<BASE_URL>/api/v1/cases/:caseId' \
--header 'cv-api-key: <redacted>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "action": "UPDATE_ESCALATION",
  "escalations": [
    {
      "escalationId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "note": "Patient confirmed new address.",
      "followUpDueAt": "2025-06-15T09:00:00.000Z",
      "assignedToEmail": "newagent@example.com"
    }
  ]
}'

JavaScript

const caseId = 'YOUR_CASE_ID';

const response = await fetch(
`https://api.care360-next.carevalidate.com/api/v1/cases/${caseId}`,
{
  method: 'POST',
  headers: {
    'cv-api-key': 'YOUR_SECRET_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    action: 'UPDATE_ESCALATION',
    escalations: [
      {
        escalationId: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
        note: 'Patient confirmed new address.',
        followUpDueAt: '2025-06-15T09:00:00.000Z',
        assignedToEmail: 'newagent@example.com',
      },
    ],
  }),
}
);

const data = await response.json();
console.log(data);

Python

import requests

case_id = "YOUR_CASE_ID"
url = f"https://api.care360-next.carevalidate.com/api/v1/cases/{case_id}"

headers = {
  "cv-api-key": "YOUR_SECRET_KEY",
  "Content-Type": "application/json",
}

payload = {
  "action": "UPDATE_ESCALATION",
  "escalations": [
      {
          "escalationId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
          "note": "Patient confirmed new address.",
          "followUpDueAt": "2025-06-15T09:00:00.000Z",
          "assignedToEmail": "newagent@example.com",
      }
  ],
}

response = requests.post(url, headers=headers, json=payload)
data = response.json()
print(data)

Responses

▶200SuccessEscalation(s) updated successfully. Returns the updated list of active escalations for the case.

{
  "status": 200,
  "success": true,
  "message": "Escalation(s) updated successfully",
  "data": {
    "escalations": [
      {
        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "type": "support",
        "title": "Address verification",
        "note": "Patient confirmed new address.",
        "followUpDueAt": "2025-06-15T09:00:00.000Z",
        "assignedToUserId": "u1v2w3x4-y5z6-7890-abcd-ef1234567890",
        "isCompleted": false,
        "createdAt": "2025-05-10T08:00:00.000Z",
        "updatedAt": "2025-05-19T09:00:00.000Z"
      }
    ]
  }
}

▶400Escalation Not FoundOne or more escalationId values were not found among the active escalations for this case. The response includes the current active escalations so you can identify valid IDs.

{
  "status": 400,
  "success": false,
  "error": "Escalation not found: b9c8d7e6-f5a4-3210-fedc-ba9876543210",
  "data": {
    "escalations": [
      {
        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "type": "support",
        "title": "Address verification",
        "note": null,
        "followUpDueAt": null,
        "assignedToUserId": null,
        "isCompleted": false,
        "createdAt": "2025-05-10T08:00:00.000Z"
      }
    ]
  }
}

▶400Validation Error — Invalid UUIDAn escalationId is not a valid UUID.

{
  "status": 400,
  "code": "VALIDATION_ERROR",
  "error": "escalations.0.escalationId, escalationId must be a valid UUID"
}

▶400Validation Error — Unknown FieldAn escalation update item contains a field that is not part of the schema.

{
  "status": 400,
  "code": "VALIDATION_ERROR",
  "error": "escalations.0.unknownField, Unrecognized key(s) in object: 'unknownField'"
}

▶400Validation Error — Empty ArrayThe `escalations` array is empty.

{
  "status": 400,
  "code": "VALIDATION_ERROR",
  "error": "escalations, At least one escalation is required"
}

▶400Assignee Not Found`assignedToEmail` was provided but no CVTPA user with that email exists in this organization.

{
  "status": 400,
  "success": false,
  "message": "Invalid request",
  "error": "No assignable user found with email agent@example.com for this organization"
}

▶400Case Not FoundNo case exists with the provided caseId.

{
  "status": 400,
  "success": false,
  "message": "Invalid request",
  "error": "Case not found!"
}

▶401Permission DeniedThe case belongs to a different organization than the one associated with the API key.

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

Try It Out

Try itAPI Playground

▶