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: Cancellation, Hold Order, Missing ID, ID received -ready to process, Missed appointment -reschedule, Order Medication, Waiting for patient reply, Lab request, Payment Link Generated, Payment Received, Missing CIF, Payment Confirmation Received, Payment: Refund Request, Waiting on Pharmacy reply, Waiting on External support reply, Patient has responded, Call Back Needed - English, Call Back Needed - Spanish, Possible Dispute, Lab Results Uploaded, DoseSpot Order Approved, Case Denied, Delivery/Fulfillment Issue, Billing Question, NURSING - Nurse Contact Request (Messaging), OUTBOUND - Welcome Call, CAREAGENT - Product Add-on

⚠️ Deprecated support titles — still accepted but automatically mapped to their replacement.
Address verification → Waiting for patient reply · Cancel Rx with Pharmacy → Waiting on Pharmacy reply · Dose questions → NURSING - Nurse Contact Request (Messaging) · Broken contents, Incorrect package contents, Misdelivery, Non-receipt of medication, Order delays, Refill not processed, Shipping Delays, Temperature concerns → Delivery/Fulfillment Issue · Order on a later date, Patient on vacation delay shipping → Hold Order · Patient has a question → Patient has responded · Price question, Promo code questions → Billing Question

clinical: 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, Place DoseSpot Order, Refill Ready for Review, New Patient Sync Callback

external: 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
JavaScript
Python

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"
    }
  ]
}'

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);

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

▶

Parameters​

Examples​

Responses​

Try It Out​

Parameters

Examples

Responses

Try It Out