Skip to main content

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

ParameterTypeDescriptionFormat/Validation
startTimestringStart of the date rangeISO 8601 datetime format (e.g., "2024-01-01T00:00:00Z")
endTimestringEnd of the date rangeISO 8601 datetime format (e.g., "2024-01-31T23:59:59Z")

Optional Parameters

ParameterTypeDefaultDescription
statusstring-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
recordsPerPageinteger20Number of records per page (max: 100)
afterstring-Cursor for pagination. Use cursor.end from previous response
includeAttachmentsbooleanfalseInclude attachment URLs/content for case and comments
includeOrdersbooleanfalseInclude pharmacy order details
includeCalendarEventsbooleanfalseInclude calendar event data
documentFormatstring-Format for attachment content. Values: "base64" or "url". Required when includeAttachments=true

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

FieldTypeDescription
cursorobjectContains start (first case ID) and end (last case ID)
hasNextPagebooleanWhether more pages exist after current page
hasPreviousPagebooleanWhether pages exist before current page

Case Object Structure

Each case in the cases array contains:

FieldTypeDescription
idstring (UUID)Unique identifier for the case
shortIdstringHuman-readable short ID (e.g., "ADA-ABC123")
statusstringCurrent case status
titlestringCase title
typestringCase type
isArchivedbooleanWhether the case is archived
isEscalatedbooleanWhether the case is escalated
isImportedbooleanWhether the case was imported
referralCodestringReferral code if applicable
createdAtstring (ISO 8601)Case creation timestamp
updatedAtstring (ISO 8601)Last update timestamp
assignedAtstring (ISO 8601)Assignment timestamp
inProgressAtstring (ISO 8601)In-progress start timestamp
closedAtstring (ISO 8601)Case closure timestamp
archiveReasonstringReason for checking
archiveNotestringNote for archiving
submitterobjectSubmitter (Detailed User)
productBundleobjectProduct bundle information
assignedToobjectPrimary assignee (Basic User)
assignedByobjectUser who assigned the case (Basic User)
closedBystringUser ID who closed the case
inProgressBystringUser ID who marked case as in progress
hrRepobjectHR Representative (Basic User)
assigneesarrayArray of additional assignees objects
decisionsarrayArray of decision objects
activityarrayArray of activity logs
commentsarrayArray of comment objects (non-restricted)
notesarrayArray of internal notes (restricted comments)
ordersarrayPharmacy order details (when includeOrders=true)
paymentsarrayArray of payment objects
attachmentsarrayCase attachments with URL/content (when includeAttachments=true)
calendarEventsarrayCalendar events (when includeCalendarEvents=true)
responsesarrayForm responses with answers
productsarrayCase 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:

FieldTypeDescription
idstring (UUID)Case product ID
subscriptionobject or nullSubscription 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):

FieldTypeDescription
intervalstring | nullOne of: "day", "week", "month", "year" (lowercase). Can be null.
intervalCountnumber | nullPositive 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.):

FieldType
idstring
firstNamestring
lastNamestring

Detailed User (used for submitter):

FieldTypeDescription
idstringUser ID
emailstringUser email
firstNamestringUser first name
lastNamestringUser last name
phoneNumberstringUser phone number
dobstringDate of birth
genderstringUser gender
addressstringAddress line 1
address2stringAddress line 2
citystringCity
statestringState
postalCodestringPostal code

Decision Object

FieldTypeDescription
idstring (UUID)Decision ID
isApprovedbooleanWhether approved
isNoDecisionbooleanWhether no decision made
isPaidbooleanWhether decision is paid
startDatestringDecision start date
endDatestringDecision end date
decisionTextstringText description of the decision
categorystringDecision category
visitTypestringType of visit
productIdstring (UUID)Related product ID
createdAtstring (ISO 8601)Creation timestamp
addedByobjectUser who added the decision (see Decision AddedBy Object)
medInfoarrayArray of medication information objects (see MedInfo Object)

Decision AddedBy Object

FieldTypeDescription
idstringUser ID
firstNamestringFirst name
lastNamestringLast name
titlestringTitle (e.g., MD, DO)
titleSuffixstringTitle suffix
emailstringEmail address
phoneNumberstringPhone number
npistringNPI number
deastringDEA number
addressstringAddress line 1
address2stringAddress line 2
citystringCity
statestringState
postalCodestringPostal code
countrystringCountry

MedInfo Object

FieldTypeDescription
idstring (UUID)MedInfo ID
externalIdstring or nullExternal ID
medicinestringMedicine/Drug name
isRefillbooleanWhether this is a refill
dosagestringDosage information
refillCountintegerNumber of refills
pharmacyInstructionsstringInstructions for pharmacy
dosingFrequencystringDosing frequency
treatmentPeriodstringTreatment period
isPriorAuthRequestedbooleanWhether prior authorization was requested
orderNotestringOrder notes

Activity Object

FieldType
idstring
typestring
isPHIboolean
isRestrictedboolean
timestampstring
valueBeforestring
valueAfterstring

Attachment Object (when includeAttachments=true)

FieldTypeDescription
idstring (UUID)Attachment ID
fileNamestringFile name
isPHIbooleanWhether contains PHI
isRestrictedbooleanWhether attachment is restricted
createdAtstring (ISO date)Upload timestamp
uploadedByobjectUser who uploaded the file (Basic User)
urlstringSigned URL (when documentFormat=url)

Payment Object

FieldTypeDescription
idstring (UUID)Payment ID
amountstringPayment amount
statusstringPayment status (e.g., PAID, PENDING)
descriptionstringPayment description
dueDatestring (ISO date)Payment due date
paymentDatestring (ISO date)Date payment was made
cancellationDatestring (ISO date)Date payment was cancelled
isScheduledbooleanWhether payment is scheduled
isAutoCreatedbooleanWhether payment was auto-created
feesobjectFee breakdown (consult, pharmacy, shipping, etc.) including subFees array
createdByobjectUser who created the invoice (Basic User + email)

Calendar Event Object (when includeCalendarEvents=true)

FieldTypeDescription
idstring (UUID)Event ID
startDateTimestring (ISO date)Start time
endDateTimestring (ISO date)End time
timezonestringTimezone
meetingLinkstringVideo meeting link
meetingProviderstringMeeting provider (e.g. zoom, google_meet)
cancelURLstringURL to cancel meeting
rescheduleURLstringURL to reschedule meeting
providerNamestringName of the provider
providerEmailstringEmail of the provider

Order Object (when includeOrders=true)

KEYTYPENOTES
idstringInternal Order ID
externalIdstring (UUID)External Order ID (Pharmacy)
pharmacyOrderIdstringPharmacy's internal order ID
trackingIdstring or nullTracking number
statusstringOrder status (e.g., Draft, Placed, Shipped)
messagestring or nullError message or status note
pharmacyNamestringName of the pharmacy
createdAtstring (ISO date)Order creation date
itemsarrayList of items in the order
replacementReasonstring or nullReason for replacement (if applicable)
shippingLogsarrayShipping history logs
estDeliveryAtstring (ISO date) or nullEstimated delivery date
trackingUrlstring or nullURL to track the shipment
carrierNamestring or nullShipping carrier name (e.g., FedEx, UPS)

Order Item Object

KEYTYPENOTES
idstringItem ID
namestringDrug name
quantitystringQuantity ordered

Order Shipping Log Object

KEYTYPENOTES
statusUpdatedAtstring (ISO date)Date status was updated
locationstring or nullLocation of the package
messagestring or nullStatus message
statusstring or nullShipping 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

StatusDescription
OPENCase has been created but not yet assigned
ASSIGNEDCase has been assigned to a care provider
IN_PROGRESSCase is actively being worked on
APPROVEDCase has been approved/resolved positively
REJECTEDCase has been rejected/denied
NO_DECISIONCase closed without a decision
ABANDONEDCase was abandoned before payment

Case product subscription (API summary)

AreaChange
GET /api/v1/casesResponse: each case includes a products array; each product has id and subscription intervalCount.
POST /api/v1/cases/:caseId/productsRequest: each product may include optional subscription intervalCount.
GraphQL CaseProductNew field subscription (type CaseProductSubscription). New type CaseProductSubscription with interval and intervalCount.

Changelog

VersionDateChanges
1.02024-12-16Initial Get Cases API documentation
1.12025-02-11Response: each case includes products array with id and optional subscription intervalCount.