Get Cases API

GET/api/v1/cases

Retrieves cases within a date range. Supports status filtering and cursor-based pagination. Returns case details including submitter info, product bundles, decisions, orders, attachments, calendar events, and form responses.

cv-api-key

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

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

Authentication

Headers

cv-api-keystringrequired

Your organization's secret API key provided by CareValidate.

Query Parameters

Required Parameters

startTimestringrequired

Start of the date range. ISO 8601 datetime format.

Example: 2024-01-01T00:00:00Z

endTimestringrequired

End of the date range. ISO 8601 datetime format.

Example: 2024-01-31T23:59:59Z

Optional Parameters

statusstringoptional

Filter by status(es). Supports comma-separated values for multiple statuses.

Example: OPEN,APPROVED,IN_PROGRESS

Values:OPENASSIGNEDIN_PROGRESSAPPROVEDREJECTEDNO_DECISIONABANDONED

recordsPerPageintegeroptional

Number of records per page (max: 100). Defaults to 20.

Example: 20

afterstringoptional

Cursor for pagination. Use cursor.end from previous response.

includeAttachmentsbooleanoptional

Include attachment URLs/content for case and comments. Defaults to false.

includeOrdersbooleanoptional

Include pharmacy order details. Defaults to false.

includeCalendarEventsbooleanoptional

Include calendar event data. Defaults to false.

documentFormatstringoptional

Format for attachment content. Required when includeAttachments=true.

Values:base64url

Query Parameter Validation

1. Date Format: Both startTime and endTime must be valid ISO 8601 datetime strings
2. Date Range: endTime must be later than startTime
3. Maximum Range: Date range cannot exceed 60 days
4. Status: If provided, each status must be one of the valid case statuses
5. recordsPerPage: Must be a positive integer, max 100

Response Object Details

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. 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.

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, subscription can 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

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 {'interval', {'intervalCount'}.
POST /api/v1/cases/:caseId/products	Request: each product may include optional subscription {'interval', {'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 {'interval', {'intervalCount'}.

Request Examples

cURL

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"

JavaScript

const params = new URLSearchParams({
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',
});

const response = await fetch(
`https://api.care360-next.carevalidate.com/api/v1/cases?${params}`,
{
  method: 'GET',
  headers: {
    'cv-api-key': 'YOUR_SECRET_KEY_HERE',
  },
}
);

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

Python

import requests

url = "https://api.care360-next.carevalidate.com/api/v1/cases"
headers = {
  "cv-api-key": "YOUR_SECRET_KEY_HERE"
}
params = {
  "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",
}

response = requests.get(url, headers=headers, params=params)
data = response.json()
print(data)

Additional cURL 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"

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"

Responses

▶200SuccessCases retrieved successfully with pagination info.

{
  "status": 200,
  "success": true,
  "data": {
    "cases": [
      "..."
    ],
    "pageInfo": {
      "cursor": {
        "start": "uuid-1",
        "end": "uuid-n"
      },
      "hasNextPage": true,
      "hasPreviousPage": false
    },
    "count": 20
  }
}

▶401Authentication Error

{
  "status": 401,
  "success": false,
  "message": "Invalid request",
  "error": "Unauthorized"
}

▶400Missing Required Parameters

{
  "status": 400,
  "success": false,
  "message": "Invalid request parameters",
  "error": "startTime must be a valid ISO 8601 datetime"
}

▶400Invalid Date Range

{
  "status": 400,
  "success": false,
  "message": "Invalid request parameters",
  "error": "endTime must be later than startTime"
}

▶400Date Range Too Large

{
  "status": 400,
  "success": false,
  "message": "Invalid request parameters",
  "error": "Date range between startTime and endTime cannot exceed 60 days"
}

▶400Invalid 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"
}

Try It Out

Try itAPI Playground

▶