Filters & Sorting
Filtering allows you to reduce the dataset returned by filtering on key parameters
API - Filtering Guide
This guide explains how to apply filters when making API requests to https://api.heim.health/v1/.
Filter Syntax
Filters follow the format:
?filter=<field><operator><value><field>: The property you want to filter on (e.g.,createdAt).<operator>: The comparison operator (:,>,<,>=,<=,~).<value>: The specific value to filter for. (value).
Supported Comparison Operators
| Operator | Description | Example |
|---|---|---|
: | Equals | filter=externalRef:"test_external_ref" |
> | Greater than | filter=updatedAt>"2024-08-29" |
< | Less than | filter=createdAt<"2024-01-01" |
>= | Greater than or equal | filter=createdAt>="2024-02-01" |
<= | Less than or equal | filter=createdAt<="2024-03-01" |
~ | Contains (for string fields) | filter=patient.name~"John" |
Step-by-Step Guide to Using Filters
Step 1: Start with the Base URL
Every API request begins with the base URL:
https://api.heim.health/v1/Step 2: Select the Resource Type
Choose whether you want to filter appointments or patients by appending it to the base URL:
https://api.heim.health/v1/appointments/Or:
https://api.heim.health/v1/patients/Step 3: Add the?filter= Parameter
?filter= ParameterTo apply a filter, append ?filter= to the URL.
Step 4: Choose the Field to Filter By
Identify which field you want to filter results by. Common fields include:
createdAt(timestamp when the record was created)updatedAt(timestamp when the record was last updated)patient.id(unique identifier of the patient)
Step 5: Select an Operator
Choose a comparison operator from the supported list:
:(equals)>(greater than)<(less than)>=(greater than or equal)<=(less than or equal)~(contains, for string fields)
Step 6: Provide a Value
Ensure the value matches the expected format:
- Ids: Quoted ("
value"). - Strings: Quoted ("
value"). - Numbers: No quotes (
123). - Dates/Timestamps: Quoted ("
value").
Step 7: Construct the Full URL
Now, put it all together. Here are some examples:
Example 1: Get appointments by external Ref
https://api.heim.health/v1/appointments/?filter=externalRef:"test_external_ref"Example 2: Get appointments updated after a certain date
https://api.heim.health/v1/appointments/?filter=updatedAt>"2024-08-29"Step 8: Combine Filters with Other Query Parameters
Filters can be combined with other parameters like limit and sort:
https://api.heim.health/v1/appointments/?filter=patient.id:"p_E9eHUQsSM5pfQ2yp6W"&limit=3&sort=createdAt:ascAppointments API
The Appointments API supports filtering on various fields using specific operators. This guide outlines the available filters, their syntax, and examples.
Supported Filters by Field
| Field | Equals (:) | Greater Than (>) | Less Than (<) | Greater/Equal (>=) | Less/Equal (<=) | Contains (~) |
|---|---|---|---|---|---|---|
id | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
organisationId | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
externalRef | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
note | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
status (new, completed, cancelled) | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
startAfter | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
completeBefore | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
estimatedTimeOfArrival | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
completionNotes | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
phoneNumber | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
createdAt | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ |
updatedAt | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ |
completedAt | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
patient.id | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
task.id | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
window.id | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
practitioner.id | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
patient.firstName | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
patient.lastName | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
Sorting
- The
sortparameter allows sorting results based on date or datetime fields. - Sorting syntax:
sort=<field>:ascorsort=<field>:desc. - Only date or datetime fields (e.g.,
createdAt,updatedAt) support sorting.
Example:
https://api.heim.health/v1/appointments/?sort=createdAt:descLimit & Offset
limit: Defines the maximum number of results returned per request.offset: Skips a specified number of results before starting to return data.- Usage of
offsetis beneficial for pagination when fetching large datasets.
Example:
https://api.heim.health/v1/appointments/?limit=10&offset=20- This query retrieves 10 results, skipping the first 20.
Using Multiple Filters
AND: Allows you to combine multiple filters in a single query.
Note: Ensure there are spaces on both sides of AND for correct syntax.
Example:
https://api.heim.health/v1/appointments/?filter=createdAt>2025-01-12 AND createdAt<2025-02-12Example API Calls
-
Filter by
externalRef:https://api.heim.health/v1/appointments/?filter=externalRef:"test_external_ref" -
Filter by
updatedAtgreater than a specific date:https://api.heim.health/v1/appointments/?filter=updatedAt>"2024-08-29" -
Filter by
patient.idand sort bycreatedAtin ascending order:https://api.heim.health/v1/appointments/?filter=patient.id:"p_E9eHUQsSM5pfQ2yp6W"&limit=3&sort=createdAt:asc
Schema Mapping and Data Types
The API follows an ElasticSearch-based schema where fields are mapped to specific types:
- Date Fields:
timestamp,createdAt,updatedAt,planFrom,planTo,window.date,window.startAt. - Keyword Fields:
id,status,assignmentStatus,practitioner.id,task.id,window.id,organisation.id. - Text Fields (support full-text search with
~operator):externalRef,location.postalCode,practitioner.firstName,practitioner.lastName. - Boolean Fields:
isTest. - Geo Fields:
geoPoint.
The : operator matches precisely on keyword fields, whereas ~ applies to text fields for full-text search.
Patients API:
Supported Filters by Field
| Field | Equals (:) | Greater Than (>) | Less Than (<) | Greater/Equal (>=) | Less/Equal (<=) | Contains (~) |
|---|---|---|---|---|---|---|
externalRef | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
Example API Calls
Filter byexternalRef :
https://api.heim.health/v1/patients/?filter=externalRef:test_external_refConclusion
This guide provides an overview of available filters and how to use them. Ensure your queries follow the correct syntax, and refer to the supported filters table for guidance.
For any discrepancies or additional filter support, please contact the API team.
Updated 6 months ago