Patients API
Manage patient records for your organization. Patient data is essential for making calls and includes contact information and optional metadata.
List Patients
Retrieve a paginated list of patients for your organization.
GET /api/v1/patients
Purpose
Lists all patients belonging to your organization with pagination support.
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 |
Response
{
"data": [
{
"id": "22222222-2222-2222-2222-222222222222",
"first_name": "John",
"last_name": "Doe",
"birth_date": "1990-01-01",
"phone_number": "+15555551234",
"email": "john.doe@email.com", // nullable
"health_card_number": "1234567890", // nullable
"created_at": "2024-01-15T10:00:00.000Z",
"updated_at": "2024-01-15T10:00:00.000Z"
}
],
"pagination": {
"start": 1,
"requested_size": 100,
"returned_count": 25
}
}
Response Fields
data: Array of patient objectspagination.start: The 1-based index you requestedpagination.requested_size: The size parameter you providedpagination.returned_count: Actual number of patients returned
Error Responses
400 Bad Request: Invalid pagination parameters- "Invalid start parameter (must be >= 1)"
- "Invalid size parameter (must be 1-500)"
Example
# Get first page with default size
curl -X GET "https://orchestrator.helloblair.com/api/v1/patients" \
-H "X-API-Key: YOUR_API_KEY"
# Get second page with custom size
curl -X GET "https://orchestrator.helloblair.com/api/v1/patients?size=50&start=51" \
-H "X-API-Key: YOUR_API_KEY"
Get Patient
Retrieve details for a specific patient.
GET /api/v1/patients/{patientId}
Purpose
Get comprehensive information about a specific patient.
Path Parameters
| Parameter | Type | Description |
|---|---|---|
patientId | uuid | The unique identifier of the patient |
Response
{
"id": "22222222-2222-2222-2222-222222222222",
"first_name": "John",
"last_name": "Doe",
"birth_date": "1990-01-01",
"phone_number": "+15555551234",
"email": "john.doe@email.com",
"health_card_number": "1234567890",
"created_at": "2024-01-15T10:00:00.000Z",
"updated_at": "2024-01-15T10:00:00.000Z"
}
Response
Returns the complete patient record with all fields.
Error Responses
400 Bad Request: "Invalid patient ID" - Patient not found or doesn't belong to your organization
Example
curl -X GET https://orchestrator.helloblair.com/api/v1/patients/YOUR_PATIENT_ID \
-H "X-API-Key: YOUR_API_KEY"
Create Patient
Add a new patient to your organization.
POST /api/v1/patients
Purpose
Creates a new patient record in your organization.
Request Body
{
"first_name": "John", // Required: Patient's first name (non-empty)
"last_name": "Doe", // Required: Patient's last name (non-empty)
"birth_date": "1990-01-01", // Required: Birth date (ISO 8601 date string)
"phone_number": "+15555551234", // Required: Phone number (non-empty)
"email": "john.doe@email.com", // Optional: Email address (valid format)
"health_card_number": "1234567890" // Optional: Health card number
}
Field Validation
first_name: Required string, cannot be emptylast_name: Required string, cannot be emptybirth_date: Required ISO 8601 date stringphone_number: Required string, cannot be emptyemail: Optional, must be valid email format if providedhealth_card_number: Optional string
Response
{
"id": "22222222-2222-2222-2222-222222222222",
"first_name": "John",
"last_name": "Doe",
"birth_date": "1990-01-01",
"phone_number": "+15555551234",
"email": "john.doe@email.com",
"health_card_number": "1234567890",
"created_at": "2024-01-15T10:00:00.000Z",
"updated_at": "2024-01-15T10:00:00.000Z"
}
Notes
- The system automatically assigns a UUID to the new patient
created_atandupdated_atare set to the current timestamp
Example
curl -X POST https://orchestrator.helloblair.com/api/v1/patients \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"first_name": "John",
"last_name": "Doe",
"birth_date": "1990-01-01",
"phone_number": "+15555551234",
"email": "john.doe@email.com"
}'
Update Patient
Modify an existing patient's information.
PUT /api/v1/patients/{patientId}
Purpose
Updates one or more fields of an existing patient record.
Path Parameters
| Parameter | Type | Description |
|---|---|---|
patientId | uuid | The unique identifier of the patient |
Request Body
All fields are optional - only include fields you want to update:
{
"first_name": "Jane", // Optional: Updated first name
"last_name": "Smith", // Optional: Updated last name
"birth_date": "1990-01-01", // Optional: Updated birth date
"phone_number": "+15555559999", // Optional: Updated phone number
"email": "jane.smith@email.com", // Optional: Updated email
"health_card_number": "9876543210" // Optional: Updated health card
}
Field Validation
first_name: Optional stringlast_name: Optional stringbirth_date: Optional ISO 8601 date stringphone_number: Optional stringemail: Optional, must be valid email format if providedhealth_card_number: Optional string
Response
{
"id": "22222222-2222-2222-2222-222222222222",
"first_name": "Jane",
"last_name": "Smith",
"birth_date": "1990-01-01",
"phone_number": "+15555559999",
"email": "jane.smith@email.com", // nullable
"health_card_number": "9876543210", // nullable
"created_at": "2024-01-15T10:00:00.000Z",
"updated_at": "2024-01-15T15:30:00.000Z"
}
Notes
- Only fields included in the request are updated
updated_atis automatically updated to the current timestamp- Returns the complete updated patient record
Error Responses
400 Bad Request: "Invalid patient ID" - Patient not found or doesn't belong to your organization
Example
curl -X PUT https://orchestrator.helloblair.com/api/v1/patients/YOUR_PATIENT_ID \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"phone_number": "+15555559999",
"email": "newemail@example.com"
}'
Delete Patient
Remove a patient from your organization.
DELETE /api/v1/patients/{patientId}
Purpose
Permanently deletes a patient record from your organization.
Path Parameters
| Parameter | Type | Description |
|---|---|---|
patientId | uuid | The unique identifier of the patient |
Response
{
"message": "Patient [patientId] deleted successfully"
}
Error Responses
400 Bad Request: "Invalid patient ID" - Patient not found or doesn't belong to your organization
Notes
- This operation is permanent and cannot be undone
- All associated data may be affected (check your data retention policies)
- The patient must belong to your organization
Example
curl -X DELETE https://orchestrator.helloblair.com/api/v1/patients/YOUR_PATIENT_ID \
-H "X-API-Key: YOUR_API_KEY"
Data Formats
Phone Numbers
Phone numbers should be provided in E.164 format:
- Format:
+[country code][subscriber number] - US Example:
+14155552671 - UK Example:
+442071838750
Dates
All dates use ISO 8601 format:
- Format:
YYYY-MM-DD - Example:
1990-01-01
Timestamps
API responses return timestamps in ISO 8601 format with UTC timezone:
- Response format:
YYYY-MM-DDTHH:mm:ss.sssZ - Response example:
2024-01-15T10:00:00.000Z
API requests accept ISO 8601 timestamps with any timezone offset:
- Request examples:
2024-01-15T10:00:00.000Z,2024-01-15T10:00:00.000+00:00,2024-01-15T10:00:00.000-05:00
Best Practices
- Validate phone numbers before creating patients - ensure they're reachable
- Use consistent date formats - always use ISO 8601 (YYYY-MM-DD)
- Implement pagination when listing many patients
- Handle errors gracefully - check for 400 errors when patient not found
- Keep patient data up to date - update phone numbers and emails as needed
- Use 1-based pagination - the start parameter begins at 1, not 0
Error Messages
Common Error Responses
400 Bad Request: "Invalid patient ID" - Patient not found or doesn't belong to organization400 Bad Request: "Invalid start parameter (must be >= 1)" - Pagination start less than 1400 Bad Request: "Invalid size parameter (must be 1-500)" - Pagination size out of range500 Internal Server Error: "Internal Server Error" - Server-side error