Cases API
Retrieve case information by external identifier. This endpoint allows you to fetch case details including patient information, scheduling status, and retry attempt tracking.
Get Cases
Retrieve a paginated list of cases for your organization.
GET /api/v1/cases
Purpose
Lists all cases for your organization with pagination support and optional filtering by status and update date.
Query Parameters
| Parameter | Type | Required | Description | Default | Range |
|---|---|---|---|---|---|
size | integer | No | Number of results per page | 100 | 1-500 |
start | integer | No | Starting index (1-based) | 1 | >= 1 |
updated_after | ISO 8601 string | No | Filter cases updated after this date | All cases | - |
status | string | No | Filter by case status | All statuses | awaiting_sms, awaiting_call, cancelled, pending, success, escalation |
Response
{
"data": [
{
"id": "11111111-1111-1111-1111-111111111111",
"name": "Case 2025-10-15",
"created_at": "2025-10-15T10:00:00.000Z",
"external_id_field_name": "sample_field_name",
"external_id": "1234567",
"patient_id": "11111111-1111-1111-1111-111111111111",
"attempt_count": 0,
"max_attempts": 3,
"updated_at": "2025-10-15T10:30:00.000Z",
"status": "success",
"case_report": {
// **NOTE** Content varies by agent configuration
"tickets": [],
"extracted_data": {
"end_case": "case_1",
"allergies": [
{
"name": "grass",
"reaction": "rash",
"severity": "mild"
}
],
"medications": [
{
"name": "Methylphenidate",
"dosage": "20mg",
"duration": "1 year",
"frequency": "1 time a day"
},
{
"name": "Acetaminophen/Guaifenesin",
"dosage": "20mg",
"duration": "1 year",
"frequency": "1 time a day"
}
],
"pharmacy_fax": "+19053173538",
"consent_given": "yes",
"pharmacy_name": "SHOPPERS DRUG MART",
"preferred_email": "john.doe@example.com",
"identity_verified": "yes",
"ohip_version_code": "AB",
"flagged_medications": [],
"faq_answered_from_kb": [
{
"question": "pet_policy",
"answer": "Pets are not allowed during the appointment."
},
{
"question": "service_dog_policy",
"answer": "Service dogs are welcome to accompany you during your appointment."
},
{
"question": "bring_medications_list",
"answer": "Yes, please bring a complete list of your current medications and supplements."
}
],
"appointment_confirmed": "yes",
"preferred_phone_number": "+14165551234"
},
"short_description": "Cardiology intake completed successfully; all information collected.",
"bullet_point_summary": [
"Patient identity verified and consent obtained.",
"All intake questions completed; appointment confirmed."
],
"conversation_summary": "The agent successfully contacted the patient to conduct a cardiology intake. Identity verification and consent were obtained. All required intake information was collected including medications, allergies, and pharmacy details. The appointment was confirmed and all patient questions were answered. The intake process was completed successfully."
}
},
{
"id": "22222222-2222-2222-2222-222222222222",
"name": "Case 2025-10-15",
"created_at": "2025-10-15T10:00:00.000Z",
"external_id_field_name": "sample_field_name",
"external_id": "1234567",
"patient_id": "22222222-2222-2222-2222-222222222222",
"attempt_count": 0,
"max_attempts": 3,
"updated_at": "2025-10-15T10:30:00.000Z",
"status": "success",
"case_report": {
// **NOTE** Content varies by agent configuration
"tickets": [],
"extracted_data": {
"end_case": "case_1",
"allergies": [],
"medications": [],
"pharmacy_fax": "",
"consent_given": "yes",
"flagged_medications": [],
"pharmacy_name": "SHOPPERS DRUG MART",
"preferred_email": "jane.smith@email.com",
"identity_verified": "yes",
"ohip_version_code": "N/A",
"faq_answered_from_kb": [],
"appointment_confirmed": "yes",
"preferred_phone_number": "+16475559876"
},
"short_description": "Cardiology intake completed successfully; patient reported no medications or allergies.",
"bullet_point_summary": [
"Patient identity verified and consent obtained.",
"Intake questions completed; patient has no current medications or allergies.",
"Appointment confirmed; no pharmacy information needed."
],
"conversation_summary": "The agent successfully contacted the patient to conduct a cardiology intake. Identity verification and consent were obtained. During the intake process, the patient confirmed they are not currently taking any medications and have no known allergies. No pharmacy information was needed. The appointment was confirmed and all patient questions were answered. The intake process was completed successfully with no medical information to record."
}
},
{
"id": "33333333-3333-3333-3333-333333333333",
"name": "Case 2025-10-15",
"created_at": "2025-10-15T10:00:00.000Z",
"external_id_field_name": "sample_field_name",
"external_id": "1234567",
"patient_id": "33333333-3333-3333-3333-333333333333",
"attempt_count": 0,
"max_attempts": 3,
"updated_at": "2025-10-15T10:30:00.000Z",
"status": "pending",
"case_report": {
// **NOTE** Content varies by agent configuration
"tickets": [
{
"notes": "Patient asked a question that the agent could not answer",
"title": "FAQ Issue"
}
],
"extracted_data": {
"end_case": "case_6",
"allergies": [
{
"name": "grass",
"reaction": "rash",
"severity": "mild"
}
],
"medications": [
{
"name": "Methylphenidate",
"dosage": "20mg",
"duration": "1 year",
"frequency": "1 time a day"
},
{
"name": "Acetaminophen/Guaifenesin",
"dosage": "20mg",
"duration": "1 year",
"frequency": "1 time a day"
}
],
"pharmacy_fax": "+19053173538",
"consent_given": "yes",
"pharmacy_name": "SHOPPERS DRUG MART",
"preferred_email": "bob.jones@example.com",
"identity_verified": "yes",
"ohip_version_code": "AB",
"flagged_medications": [
{
"name": "Sandoz",
"dosage": "10mg",
"duration": "1 year",
"frequency": "2 times a day"
}
],
"faq_answered_from_kb": [
{
"question": "pet_policy",
"answer": "Pets are not allowed during the appointment."
},
{
"question": "service_dog_policy",
"answer": "Service dogs are welcome to accompany you during your appointment."
},
{
"question": "bring_medications_list",
"answer": "Yes, please bring a complete list of your current medications and supplements."
}
],
"appointment_confirmed": "yes",
"preferred_phone_number": "+14165554321"
},
"short_description": "Cardiology intake partially completed; patient asked unanswerable question.",
"bullet_point_summary": [
"Patient identity verified and consent obtained.",
"Intake questions mostly completed; flagged medication identified.",
"Patient asked a question the agent could not answer, requiring follow-up."
],
"conversation_summary": "The agent successfully contacted the patient to conduct a cardiology intake. Identity verification and consent were obtained. During the intake process, medications and allergies were collected, and a flagged medication (Sandoz) was identified. The patient asked a question that the agent could not answer from the knowledge base, resulting in a ticket being created for follow-up. Most intake information was collected, but the case remains pending due to the unanswered question requiring human review."
}
}
],
"pagination": {
"start": 1,
"requested_size": 100,
"returned_count": 3,
"total": 150,
"hasMore": false,
"updated_after": "2025-10-01T00:00:00.000Z"
}
}
Response Fields
id: Unique identifier for the casename: Name or description of the casecreated_at: ISO 8601 timestamp when the case was createdexternal_id_field_name: Name of the external ID field used to identify this caseexternal_id: External identifier from your systempatient_id: UUID of the associated patient (nullable)attempt_count: Number of call attempts made for this casemax_attempts: Maximum number of call attempts allowedupdated_at: ISO 8601 timestamp when the case was last updatedstatus: Current status of the case (awaiting_sms, awaiting_call, cancelled, pending, success, escalation)case_report: JSONB field with case-specific data (nullable)short_description: Brief one-line summary of the call outcomebullet_point_summary: Array of key points summarizing the call interactionconversation_summary: Detailed narrative summary of the entire call and its outcomepagination.start: The 1-based index you requestedpagination.requested_size: The size you requestedpagination.returned_count: Actual number of records returnedpagination.total: Total records matching the filterpagination.hasMore: Whether more pages are available
Example
# Get first page with default size
curl -X GET "https://orchestrator.helloblair.com/api/v1/cases" \
-H "X-API-Key: YOUR_API_KEY"
# Get second page with custom size
curl -X GET "https://orchestrator.helloblair.com/api/v1/cases?size=50&start=51" \
-H "X-API-Key: YOUR_API_KEY"
# Filter by status
curl -X GET "https://orchestrator.helloblair.com/api/v1/cases?status=pending" \
-H "X-API-Key: YOUR_API_KEY"
# Filter by update date and status
curl -X GET "https://orchestrator.helloblair.com/api/v1/cases?updated_after=2025-10-01T00:00:00.000Z&status=success" \
-H "X-API-Key: YOUR_API_KEY"
Case Lifecycle
After a case is created in the system and calls are scheduled, the status will progress through the following statuses:
- awaiting_sms: We have not had an interaction with the patient yet
- awaiting_call: We have sent an SMS to the patient informing that they will be called
- cancelled: Case was cancelled before making any contact with the patient
- pending: Contact has been made with the patient. We are waiting to make sure there are no missing information
- success: Intake is fully complete, no more actions remaining for this case
- escalation: Case is in a state where we can no longer handle. Requires clinic admin intervention
Best Practices
- Use pagination when retrieving large lists of cases
- Filter by status to focus on cases requiring attention (e.g.,
escalation,success) - Use updated_after to sync only recently changed cases
- Monitor case_report for agent-specific data and insights
- Use 1-based pagination - start index begins at 1, not 0
Use Cases
Monitoring Case Progress
Use the cases endpoint to:
- Track cases by status (awaiting_sms, awaiting_call, pending, success, etc.)
- Retrieve cases updated after a specific date for syncing
- Monitor case reports for completed intakes
- Identify cases requiring escalation or admin intervention