Add Escalation

POST/api/v1/cases/:caseId

Adds one or more escalations to an existing case using the ADD_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 `ADD_ESCALATION`.

Values:ADD_ESCALATION

escalationsarray of objectsrequired

One or more escalation items to add to the case. At least one item is required.

Show 5 child properties

typestringrequired

The escalation category. Must be one of: `support`, `clinical`, `external`.

Values:supportclinicalexternal

titlestringrequired

The escalation reason. Must be a valid title for the given `type`. **support titles:** Cancellation, Hold Order, Address verification, Missing ID, Patient on vacation delay shipping, Refill Request, Price question, Dose questions, Missed appointment -reschedule, Promo code questions, Non-receipt of medication, Refill not processed, Shipping Delays, Cancel Rx with Pharmacy, Patient has a question, Miscellaneous, ID received -ready to process, Order Medication, Form Answered, Waiting for patient reply, Order on a later date, Misdelivery, Incorrect package contents, Broken contents, Temperature concerns, Order cancellation requests, Order delays, Copy of script, Lab request, Payment Link Generated, Payment Received\, Missing CIF, Payment Confirmation Received, Delinquent Task, Payment: Refund Request, Payment: Superbill Request, Working on Case, Waiting on Pharmacy reply, Waiting on External support reply, Patient has responded, Call Back Needed - English, Call Back Needed - Spanish, Possible Dispute, Health Coach Review, Lab Results Uploaded, DoseSpot Order Approved, Case Denied, No Decision For Case **clinical titles:** Case missed for review, Patient has responded to providers question, Sign the medical necessity form, NURSING - Dosing Adjustment Request, Second opinion on a case, Ready for Review, Refill pending for review, NURSING - Clarification Needed on Prescription, Reviewed & Cleared to Proceed, Waiting for Patient Reply, NURSING - Medication Change Request, NURSING - Nausea Medication Request, Lab Review, Delinquent Task, NURSING - Patient Reporting Side Effects, Urgent, Multi Rx ready for review, Multi Rx refill review, NURSING - Nurse Contact Request (Phone), NURSING - Nurse Contact Request (Messaging), PROVIDER - Rx Review Needed, Provider Review - Severe Side Effect / Reaction, Provider Status Update, 3-Month Rx Bundle Review, Review Dosespot Order, Refill Ready for Review, New Patient Sync Callback **external titles:** Patient requesting to cancel Sub, ID Verification, Missing Payment, Payment Issue, Disgruntled Customer, Cost Questions, Check-in form received - Missing payment, Miscellaneous, Assignment: Assign New Provider, Zofran Request, Nursing Review, Account Manager Request, No Decision For Case, Payment Received\, Missing CIF, Virtual Consult - Sync Review, Possible Dispute, Lab Request, Lab Request Placed, Lab Results Ready for Review, Pharmacy Delay, Refund Needed, Subscription Change

notestringoptional

Optional free-text note for the escalation.

followUpDueAtstringoptional

Optional ISO 8601 datetime for when a follow-up is due (e.g. `2025-06-01T12:00:00.000Z`).

assignedToEmailstringoptional

Optional email address of a TPA user to assign the escalation to. The user must be a CVTPA account with access to this organization.

Examples

cURL

curl --location '<BASE_URL>/api/v1/cases/:caseId' \
--header 'cv-api-key: <redacted>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "action": "ADD_ESCALATION",
  "escalations": [
    {
      "type": "support",
      "title": "Refill Request",
      "note": "Patient called requesting a refill.",
      "followUpDueAt": "2025-06-01T12:00:00.000Z",
      "assignedToEmail": "agent@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: 'ADD_ESCALATION',
    escalations: [
      {
        type: 'support',
        title: 'Refill Request',
        note: 'Patient called requesting a refill.',
        followUpDueAt: '2025-06-01T12:00:00.000Z',
        assignedToEmail: 'agent@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": "ADD_ESCALATION",
  "escalations": [
      {
          "type": "support",
          "title": "Refill Request",
          "note": "Patient called requesting a refill.",
          "followUpDueAt": "2025-06-01T12:00:00.000Z",
          "assignedToEmail": "agent@example.com",
      }
  ],
}

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

Responses

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

{
  "status": 200,
  "success": true,
  "message": "Escalation(s) added successfully",
  "data": {
    "escalations": [
      {
        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "type": "support",
        "title": "Refill Request",
        "note": "Patient called requesting a refill.",
        "followUpDueAt": "2025-06-01T12:00:00.000Z",
        "assignedToUserId": "u1v2w3x4-y5z6-7890-abcd-ef1234567890",
        "isCompleted": false,
        "createdAt": "2025-05-12T10:00:00.000Z",
        "updatedAt": "2025-05-12T10:00:00.000Z"
      }
    ]
  }
}

▶400Validation Error — Invalid TypeThe `type` field is not one of `support`, `clinical`, or `external`.

{
  "status": 400,
  "code": "VALIDATION_ERROR",
  "error": "escalations.0.type, Invalid type. Must be one of: support, clinical, external"
}

▶400Validation Error — Invalid TitleThe `title` is not a valid option for the given `type`.

{
  "status": 400,
  "code": "VALIDATION_ERROR",
  "error": "escalations.0.title, Invalid title \"Unknown\" for type \"support\". Valid titles: Cancellation, Hold Order, ..."
}

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

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

▶400Validation Error — Unknown FieldAn escalation 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'"
}

▶400Duplicate in RequestThe same `type` + `title` combination appears more than once in the `escalations` array.

{
  "status": 400,
  "success": false,
  "message": "Invalid request",
  "error": "Duplicate escalation in request: support / Payment: Refund Request"
}

▶400Already Active on CaseAn escalation with the same `type` + `title` already exists and is not yet completed on this case.

{
  "status": 400,
  "success": false,
  "message": "Invalid request",
  "error": "Escalation already active on this case: support / Cancellation"
}

▶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

▶