Get Cases API
Overview
The /api/v1/cases endpoint allows third-party applications to retrieve cases for a specific date range with optional status filtering and pagination. This endpoint returns comprehensive case information including submitter details, product bundles, decisions, orders, attachments, calendar events, and form responses.
Endpoint Details
Base URLs
- Production:
https://api.care360-next.carevalidate.com/api/v1/cases - Staging:
https://api-staging.care360-next.carevalidate.com/api/v1/cases
Method: GET
Content-Type: application/json
Authentication
Required Headers
cv-api-key: your-secret-api-key
The cv-api-key is your organization's secret API key provided by CareValidate.
Query Parameters
Required Parameters
| Parameter | Type | Description | Format/Validation |
|---|---|---|---|
startTime | string | Start of the date range | ISO 8601 datetime format (e.g., "2024-01-01T00:00:00Z") |
endTime | string | End of the date range | ISO 8601 datetime format (e.g., "2024-01-31T23:59:59Z") |
Optional Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
status | string | - | Filter by status(es). Supports comma-separated values for multiple statuses (e.g., "OPEN,APPROVED,IN_PROGRESS"). Valid values: OPEN, ASSIGNED, IN_PROGRESS, APPROVED, REJECTED, NO_DECISION, ABANDONED |
recordsPerPage | integer | 20 | Number of records per page (max: 100) |
after | string | - | Cursor for pagination. Use cursor.end from previous response |
includeAttachments | boolean | false | Include attachment URLs/content for case and comments |
includeOrders | boolean | false | Include pharmacy order details |
includeCalendarEvents | boolean | false | Include calendar event data |
documentFormat | string | - | Format for attachment content. Values: "base64" or "url". Required when includeAttachments=true |
Query Parameter Validation
- Date Format: Both
startTimeandendTimemust be valid ISO 8601 datetime strings - Date Range:
endTimemust be later thanstartTime - Maximum Range: Date range cannot exceed 60 days
- Status: If provided, each status must be one of the valid case statuses
- recordsPerPage: Must be a positive integer, max 100
Response Format
Success Response
{
"status": 200,
"success": true,
"data": {
"cases": [...],
"pageInfo": {
"cursor": { "start": "uuid-1", "end": "uuid-n" },
"hasNextPage": true,
"hasPreviousPage": false
},
"count": 20
}
}
PageInfo Object
| Field | Type | Description |
|---|---|---|
cursor | object | Contains start (first case ID) and end (last case ID) |
hasNextPage | boolean | Whether more pages exist after current page |
hasPreviousPage | boolean | Whether pages exist before current page |
Case Object Structure
Each case in the cases array contains:
| Field | Type | Description |
|---|---|---|
id | string (UUID) | Unique identifier for the case |
shortId | string | Human-readable short ID (e.g., "ADA-ABC123") |
status | string | Current case status |
title | string | Case title |
type | string | Case type |
isArchived | boolean | Whether the case is archived |
isEscalated | boolean | Whether the case is escalated |
isImported | boolean | Whether the case was imported |
referralCode | string | Referral code if applicable |
createdAt | string (ISO 8601) | Case creation timestamp |
updatedAt | string (ISO 8601) | Last update timestamp |
assignedAt | string (ISO 8601) | Assignment timestamp |
inProgressAt | string (ISO 8601) | In-progress start timestamp |
closedAt | string (ISO 8601) | Case closure timestamp |
archiveReason | string | Reason for checking |
archiveNote | string | Note for archiving |
submitter | object | Submitter (Detailed User) |
productBundle | object | Product bundle information |
assignedTo | object | Primary assignee (Basic User) |
assignedBy | object | User who assigned the case (Basic User) |
closedBy | string | User ID who closed the case |
inProgressBy | string | User ID who marked case as in progress |
hrRep | object | HR Representative (Basic User) |
assignees | array | Array of additional assignees objects |
decisions | array | Array of decision objects |
activity | array | Array of activity logs |
comments | array | Array of comment objects (non-restricted) |
notes | array | Array of internal notes (restricted comments) |
orders | array | Pharmacy order details (when includeOrders=true) |
payments | array | Array of payment objects |
attachments | array | Case attachments with URL/content (when includeAttachments=true) |
calendarEvents | array | Calendar events (when includeCalendarEvents=true) |
responses | array | Form responses with answers |
products | array | Case products; always present (see Products array). May be empty if the case has no products. |
Products array
Each case in the response includes a products array. It is always present on every case; it may be an empty array [] when the case has no case products.
Each item in products has the following shape:
| Field | Type | Description |
|---|---|---|
id | string (UUID) | Case product ID |
subscription | object or null | Subscription details for the case product. When the case product has no subscription data, subscription may be { "interval": null, "intervalCount": null } or the object may be omitted. Both interval and intervalCount can be null. |
Subscription object (when present):
| Field | Type | Description |
|---|---|---|
interval | string | null | One of: "day", "week", "month", "year" (lowercase). Can be null. |
intervalCount | number | null | Positive integer (e.g. 1, 2, 3, 6, 12). Can be null. |
Constraints:
- interval: Only
"day","week","month", or"year"(case-sensitive, lowercase). - intervalCount: Positive integer.
- When a case product has no subscription data,
subscriptioncan be null, omitted, or{ "interval": null, "intervalCount": null }; both fields may be null.
Example:
"products": [
{
"id": "9fc0d0f5-f211-4bf9-b105-485b1f29eb39",
"subscription": {
"interval": "month",
"intervalCount": 3
}
}
]
User Objects
Basic User (used for assignedTo, assignedBy, closedBy, etc.):
| Field | Type |
|---|---|
id | string |
firstName | string |
lastName | string |
Detailed User (used for submitter):
| Field | Type | Description |
|---|---|---|
id | string | User ID |
email | string | User email |
firstName | string | User first name |
lastName | string | User last name |
phoneNumber | string | User phone number |
dob | string | Date of birth |
gender | string | User gender |
address | string | Address line 1 |
address2 | string | Address line 2 |
city | string | City |
state | string | State |
postalCode | string | Postal code |
Decision Object
| Field | Type | Description |
|---|---|---|
id | string (UUID) | Decision ID |
isApproved | boolean | Whether approved |
isNoDecision | boolean | Whether no decision made |
isPaid | boolean | Whether decision is paid |
startDate | string | Decision start date |
endDate | string | Decision end date |
decisionText | string | Text description of the decision |
category | string | Decision category |
visitType | string | Type of visit |
productId | string (UUID) | Related product ID |
createdAt | string (ISO 8601) | Creation timestamp |
addedBy | object | User who added the decision (see Decision AddedBy Object) |
medInfo | array | Array of medication information objects (see MedInfo Object) |
Decision AddedBy Object
| Field | Type | Description |
|---|---|---|
id | string | User ID |
firstName | string | First name |
lastName | string | Last name |
title | string | Title (e.g., MD, DO) |
titleSuffix | string | Title suffix |
email | string | Email address |
phoneNumber | string | Phone number |
npi | string | NPI number |
dea | string | DEA number |
address | string | Address line 1 |
address2 | string | Address line 2 |
city | string | City |
state | string | State |
postalCode | string | Postal code |
country | string | Country |
MedInfo Object
| Field | Type | Description |
|---|---|---|
id | string (UUID) | MedInfo ID |
externalId | string or null | External ID |
medicine | string | Medicine/Drug name |
isRefill | boolean | Whether this is a refill |
dosage | string | Dosage information |
refillCount | integer | Number of refills |
pharmacyInstructions | string | Instructions for pharmacy |
dosingFrequency | string | Dosing frequency |
treatmentPeriod | string | Treatment period |
isPriorAuthRequested | boolean | Whether prior authorization was requested |
orderNote | string | Order notes |
Activity Object
| Field | Type |
|---|---|
id | string |
type | string |
isPHI | boolean |
isRestricted | boolean |
timestamp | string |
valueBefore | string |
valueAfter | string |
Attachment Object (when includeAttachments=true)
| Field | Type | Description |
|---|---|---|
id | string (UUID) | Attachment ID |
fileName | string | File name |
isPHI | boolean | Whether contains PHI |
isRestricted | boolean | Whether attachment is restricted |
createdAt | string (ISO date) | Upload timestamp |
uploadedBy | object | User who uploaded the file (Basic User) |
url | string | Signed URL (when documentFormat=url) |
Payment Object
| Field | Type | Description |
|---|---|---|
id | string (UUID) | Payment ID |
amount | string | Payment amount |
status | string | Payment status (e.g., PAID, PENDING) |
description | string | Payment description |
dueDate | string (ISO date) | Payment due date |
paymentDate | string (ISO date) | Date payment was made |
cancellationDate | string (ISO date) | Date payment was cancelled |
isScheduled | boolean | Whether payment is scheduled |
isAutoCreated | boolean | Whether payment was auto-created |
fees | object | Fee breakdown (consult, pharmacy, shipping, etc.) including subFees array |
createdBy | object | User who created the invoice (Basic User + email) |
Calendar Event Object (when includeCalendarEvents=true)
| Field | Type | Description |
|---|---|---|
id | string (UUID) | Event ID |
startDateTime | string (ISO date) | Start time |
endDateTime | string (ISO date) | End time |
timezone | string | Timezone |
meetingLink | string | Video meeting link |
meetingProvider | string | Meeting provider (e.g. zoom, google_meet) |
cancelURL | string | URL to cancel meeting |
rescheduleURL | string | URL to reschedule meeting |
providerName | string | Name of the provider |
providerEmail | string | Email of the provider |
Order Object (when includeOrders=true)
| KEY | TYPE | NOTES |
|---|---|---|
id | string | Internal Order ID |
externalId | string (UUID) | External Order ID (Pharmacy) |
pharmacyOrderId | string | Pharmacy's internal order ID |
trackingId | string or null | Tracking number |
status | string | Order status (e.g., Draft, Placed, Shipped) |
message | string or null | Error message or status note |
pharmacyName | string | Name of the pharmacy |
createdAt | string (ISO date) | Order creation date |
items | array | List of items in the order |
replacementReason | string or null | Reason for replacement (if applicable) |
shippingLogs | array | Shipping history logs |
estDeliveryAt | string (ISO date) or null | Estimated delivery date |
trackingUrl | string or null | URL to track the shipment |
carrierName | string or null | Shipping carrier name (e.g., FedEx, UPS) |
Order Item Object
| KEY | TYPE | NOTES |
|---|---|---|
id | string | Item ID |
name | string | Drug name |
quantity | string | Quantity ordered |
Order Shipping Log Object
| KEY | TYPE | NOTES |
|---|---|---|
statusUpdatedAt | string (ISO date) | Date status was updated |
location | string or null | Location of the package |
message | string or null | Status message |
status | string or null | Shipping status |
Complete Response Example
{
"status": 200,
"success": true,
"data": {
"cases": [
{
"id": "string (UUID)",
"type": "string",
"title": "string",
"status": "APPROVED",
"shortId": "string",
"createdAt": "string (ISO 8601)",
"updatedAt": "string (ISO 8601)",
"assignedAt": "string (ISO 8601)",
"inProgressAt": "string (ISO 8601)",
"closedAt": "string (ISO 8601)",
"isArchived": false,
"isEscalated": false,
"isImported": false,
"referralCode": null,
"closedBy": "string (UserId)",
"inProgressBy": "string (UserId)",
"archiveReason": null,
"archiveNote": null,
"productBundleId": "string (UUID)",
"productBundle": {
"id": "string (UUID)",
"name": "string"
},
"assignedTo": {
"id": "string (UserId)",
"firstName": "string",
"lastName": "string"
},
"hrRep": {
"id": "string (UserId)",
"firstName": "string",
"lastName": "string"
},
"assignedBy": {
"id": "string (UserId)",
"firstName": "string",
"lastName": "string"
},
"assignees": [
{
"assignee": {
"id": "string (UserId)",
"firstName": "string",
"lastName": "string"
}
}
],
"submitter": {
"id": "string (UserId)",
"firstName": "string",
"lastName": "string",
"email": "string",
"dob": "string or null",
"gender": "string or null",
"phoneNumber": "string or null",
"address": "string",
"address2": "string or null",
"city": "string",
"state": "string",
"postalCode": "string"
},
"activity": [
{
"id": "string (UUID)",
"type": "CREATE_CASE",
"isPHI": false,
"isRestricted": false,
"timestamp": "string (ISO 8601)",
"valueBefore": null,
"valueAfter": null
},
{
"id": "string (UUID)",
"type": "CHANGE_CASE_STATUS",
"isPHI": false,
"isRestricted": false,
"timestamp": "string (ISO 8601)",
"valueBefore": "OPEN",
"valueAfter": "ASSIGNED"
}
],
"decisions": [
{
"id": "string (UUID)",
"isApproved": true,
"isNoDecision": false,
"startDate": "string (ISO Date)",
"endDate": "string (ISO Date)",
"decisionText": "string",
"category": null,
"createdAt": "string (ISO 8601)",
"isPaid": false,
"visitType": "string",
"productId": "string (UUID)",
"medInfo": [
{
"id": "string (UUID)",
"externalId": null,
"medicine": "string",
"isRefill": false,
"dosage": "string",
"refillCount": 4,
"pharmacyInstructions": "string",
"dosingFrequency": "string",
"treatmentPeriod": "string",
"isPriorAuthRequested": false,
"orderNote": "string"
}
],
"addedBy": {
"id": "string (UserId)",
"firstName": "string",
"lastName": "string",
"title": "string or null",
"titleSuffix": "string or null",
"email": "string",
"phoneNumber": "string or null",
"npi": "string or null",
"dea": "string or null",
"address": "string or null",
"address2": "string or null",
"city": "string or null",
"state": "string or null",
"postalCode": "string or null",
"country": "string or null"
}
}
],
"comments": [
{
"id": "string (UUID)",
"text": "string",
"isRestricted": false,
"forms": [],
"createdAt": "string (ISO 8601)",
"author": {
"id": "string (UserId)",
"firstName": "string",
"lastName": "string"
},
"attachments": [
{
"id": "string (UUID)",
"isRestricted": false,
"isPHI": false,
"fileName": "string",
"isDeleted": false,
"createdAt": "string (ISO 8601)",
"uploadedBy": {
"id": "string (UserId)",
"firstName": "string",
"lastName": "string"
},
"url": "string (when documentFormat=url)",
"content": "string (when documentFormat=base64)"
}
]
}
],
"notes": [
{
"id": "string (UUID)",
"text": "string",
"isRestricted": true,
"forms": [],
"createdAt": "string (ISO 8601)",
"author": {
"id": "string (UserId)",
"firstName": "string",
"lastName": "string"
},
"attachments": [
{
"id": "string (UUID)",
"isRestricted": true,
"isPHI": false,
"fileName": "string",
"isDeleted": false,
"createdAt": "string (ISO 8601)",
"uploadedBy": {
"id": "string (UserId)",
"firstName": "string",
"lastName": "string"
},
"url": "string (when documentFormat=url)",
"content": "string (when documentFormat=base64)"
}
]
}
],
"payments": [
{
"id": "string (UUID)",
"isDeleted": false,
"description": "string",
"amount": "string",
"status": "string",
"dueDate": "string (ISO 8601)",
"paymentDate": null,
"cancellationDate": null,
"isScheduled": false,
"schedulePosition": null,
"isAutoCreated": false,
"createdAt": "string (ISO 8601)",
"updatedAt": "string (ISO 8601)",
"fees": {
"consultFee": "string",
"convenienceFee": "string",
"paymentProcessingFee": "string",
"pharmacyFee": "string",
"shippingFee": "string",
"syringeKitFee": "string",
"techPlatformFee": "string",
"subFees": [
{
"label": "string",
"amount": "string"
}
]
},
"createdBy": {
"id": "string (UserId)",
"firstName": "string",
"lastName": "string",
"email": "string"
}
}
],
"attachments": [
{
"id": "string (UUID)",
"isRestricted": false,
"isPHI": false,
"fileName": "string.png",
"isDeleted": false,
"createdAt": "string (ISO 8601)",
"uploadedBy": {
"firstName": "string",
"lastName": "string"
},
"url": "string (when documentFormat=url)",
"content": "string (when documentFormat=base64)"
}
],
"calendarEvents": [
{
"id": "string (UUID)",
"startDateTime": "string (ISO 8601)",
"endDateTime": "string (ISO 8601)",
"timezone": "string",
"meetingLink": "string",
"meetingProvider": "string",
"cancelURL": "string",
"rescheduleURL": "string",
"providerName": "string",
"providerEmail": "string"
}
],
"orders": [
{
"id": "string",
"externalId": "string (UUID)",
"pharmacyOrderId": "string",
"trackingId": "string or null",
"status": "string",
"message": "string or null",
"pharmacyName": "string",
"createdAt": "string (ISO date)",
"items": [
{
"id": "string",
"name": "string",
"quantity": "string"
}
],
"replacementReason": "string or null",
"shippingLogs": [
{
"statusUpdatedAt": "string (ISO date)",
"location": "string or null",
"message": "string or null",
"status": "string or null"
}
],
"estDeliveryAt": "string (ISO date) or null",
"trackingUrl": "string or null",
"carrierName": "string or null"
}
],
"responses": [
{
"id": "string (UUID)",
"isDraft": false,
"form": {
"id": "string (UUID)",
"name": "string",
"description": "string"
},
"responses": [
{
"id": "string (UUID)",
"isArchived": false,
"text": "string",
"createdAt": "string (ISO 8601)",
"question": {
"index": 1,
"type": "TEXT",
"text": "string",
"isPHI": false,
"options": [],
"required": false
},
"respondent": {
"id": "string (UserId)",
"firstName": "string",
"lastName": "string"
}
}
]
}
],
"products": [
{
"id": "9fc0d0f5-f211-4bf9-b105-485b1f29eb39",
"subscription": {
"interval": "month",
"intervalCount": 3
}
}
]
}
],
"pageInfo": {
"cursor": {
"start": "string (UUID)",
"end": "string (UUID)"
},
"hasNextPage": true,
"hasPreviousPage": false
},
"count": 20
}
}
Request Examples
Basic Request (All Cases)
curl -X GET "https://api.care360-next.carevalidate.com/api/v1/cases?startTime=2024-01-01T00:00:00Z&endTime=2024-01-31T23:59:59Z" \
-H "cv-api-key: YOUR_SECRET_KEY_HERE"
Request with Single Status Filter
curl -X GET "https://api.care360-next.carevalidate.com/api/v1/cases?startTime=2024-01-01T00:00:00Z&endTime=2024-01-31T23:59:59Z&status=OPEN" \
-H "cv-api-key: YOUR_SECRET_KEY_HERE"
Request with Multiple Statuses (comma-separated)
curl -X GET "https://api.care360-next.carevalidate.com/api/v1/cases?startTime=2024-01-01T00:00:00Z&endTime=2024-01-31T23:59:59Z&status=APPROVED,OPEN,IN_PROGRESS" \
-H "cv-api-key: YOUR_SECRET_KEY_HERE"
Paginated Request
# First page
curl -X GET "https://api.care360-next.carevalidate.com/api/v1/cases?startTime=2024-01-01T00:00:00Z&endTime=2024-01-31T23:59:59Z&recordsPerPage=10" \
-H "cv-api-key: YOUR_SECRET_KEY_HERE"
# Next page (use cursor.end from previous response)
curl -X GET "https://api.care360-next.carevalidate.com/api/v1/cases?startTime=2024-01-01T00:00:00Z&endTime=2024-01-31T23:59:59Z&recordsPerPage=10&after=CURSOR_END_FROM_PREVIOUS" \
-H "cv-api-key: YOUR_SECRET_KEY_HERE"
Request with Attachments (Base64)
curl -X GET "https://api.care360-next.carevalidate.com/api/v1/cases?startTime=2024-01-01T00:00:00Z&endTime=2024-01-31T23:59:59Z&includeAttachments=true&documentFormat=base64" \
-H "cv-api-key: YOUR_SECRET_KEY_HERE"
Request with Attachments (Signed URLs)
curl -X GET "https://api.care360-next.carevalidate.com/api/v1/cases?startTime=2024-01-01T00:00:00Z&endTime=2024-01-31T23:59:59Z&includeAttachments=true&documentFormat=url" \
-H "cv-api-key: YOUR_SECRET_KEY_HERE"
Request with Orders and Calendar Events
curl -X GET "https://api.care360-next.carevalidate.com/api/v1/cases?startTime=2024-01-01T00:00:00Z&endTime=2024-01-31T23:59:59Z&includeOrders=true&includeCalendarEvents=true" \
-H "cv-api-key: YOUR_SECRET_KEY_HERE"
Full Request with All Options
curl -X GET "https://api.care360-next.carevalidate.com/api/v1/cases?startTime=2024-01-01T00:00:00Z&endTime=2024-01-31T23:59:59Z&status=APPROVED,IN_PROGRESS&recordsPerPage=50&includeAttachments=true&includeOrders=true&includeCalendarEvents=true&documentFormat=url" \
-H "cv-api-key: YOUR_SECRET_KEY_HERE"
Error Responses
Authentication Error
{
"status": 401,
"success": false,
"message": "Invalid request",
"error": "Unauthorized"
}
Missing Required Parameters
{
"status": 400,
"success": false,
"message": "Invalid request parameters",
"error": "startTime must be a valid ISO 8601 datetime"
}
Invalid Date Range
{
"status": 400,
"success": false,
"message": "Invalid request parameters",
"error": "endTime must be later than startTime"
}
Date Range Too Large
{
"status": 400,
"success": false,
"message": "Invalid request parameters",
"error": "Date range between startTime and endTime cannot exceed 60 days"
}
Invalid Status
{
"status": 400,
"success": false,
"message": "Invalid request parameters",
"error": "Invalid status. Must be one of: OPEN, ASSIGNED, IN_PROGRESS, APPROVED, REJECTED, NO_DECISION, ABANDONED"
}
Case Statuses Explained
| Status | Description |
|---|---|
OPEN | Case has been created but not yet assigned |
ASSIGNED | Case has been assigned to a care provider |
IN_PROGRESS | Case is actively being worked on |
APPROVED | Case has been approved/resolved positively |
REJECTED | Case has been rejected/denied |
NO_DECISION | Case closed without a decision |
ABANDONED | Case was abandoned before payment |
Case product subscription (API summary)
| Area | Change |
|---|---|
| GET /api/v1/cases | Response: each case includes a products array; each product has id and subscription intervalCount. |
| POST /api/v1/cases/:caseId/products | Request: each product may include optional subscription intervalCount. |
| GraphQL CaseProduct | New field subscription (type CaseProductSubscription). New type CaseProductSubscription with interval and intervalCount. |
Changelog
| Version | Date | Changes |
|---|---|---|
| 1.0 | 2024-12-16 | Initial Get Cases API documentation |
| 1.1 | 2025-02-11 | Response: each case includes products array with id and optional subscription intervalCount. |