Community CareLink FHIR R4 API Documentation
​
Prerequisites
Partners wanting to integrate to Community CareLink's FHIR interoperability endpoints should contact their implementation lead to obtain the following required parameters:
-
[FHIR_HOST] - The host URI of the CCL FHIR service host where your data resides.
-
Authentication and Authorization parameters
- ​[AUTHORIZATION_AUTHORITY]
- [CLIENT_ID]
- [CLIENT_SECRET]
​​​
Authorization
All requests to our FHIR services require valid authorization and identification headers. The tokens are standard OAuth2 tokens registered partners can obtain from our Azure identity provider. Please reference the following examples for generating bearer tokens.
FHIR Resource Operations
Capabilities
Comprehensive endpoint capabilities are discoverable at the service metadata endpoint: [FHIR_HOST]/metadata. FHIR Resource read, write, and update requests require an accompanying Authorization header as described in the Authorization section of this page. Unless by special partner or contractual request, we do not delete our clinical objects in general. Rather, we typically offer the ability to "soft delete" but retain the record. Correspondingly, FHIR Delete queries are disallowed in our API except by special request, but many FHIR R4 Resources offer "active" or similar attributes that can be set to false to indicate deactivation and/or soft deletes.
​
Permissions
The bearer token supplied in the header of each request establishes the identity and organizational context of the accessing user (whether a system user or a human) and provisions data and action permissions accordingly.
By default, a service account created for a partner organization will have full create, read, update permissions for the Patients and related FHIR Resources they have authored into the system. They will also have read permission for Patients and related FHIR Resources if the Patient is both within their Organization Group and the Patient has consented to share the Resource within the Organization Group. If an organization is not the managing organization of a Patient, it may still add and then perform maintenance operations on FHIR Resources that reference the Patient. However, they will not be allowed to edit the Patient Resource itself, except to add or modify a partner-specific identifier so that Patients may then be queried using an identifier convention of your choosing.
​
Object Mappings
Our EHR and its user experiences refer to data objects using language that is common and natural for the clinical context of our partners. On the other hand, FHIR specifies a standard nomenclature on its Resource types which allows for broad interoperability across the diversity of organizations in the healthcare ecosystem. As such, the object nomenclature in our EHR experience does not exactly match the standard FHIR nomenclature. Our FHIR APIs implement the FHIR R4 standard Resource nomenclature, so it is useful to understand how that nomenclature maps onto the nomenclature partners experience in our EHR. The following table explains the mapping:​​
Community CareLink Concept | FHIR R4 Resource | Notes |
|---|---|---|
Client/Person | Patient | Person.Id will equal CCL's PersonGUID. Person.Identifier should include PersonGUID, PersonID, and any partner-specific identifying codes. All are searchable using the "identifier" attribute. |
Agency | Organization | Connected to Organization Groups using "partOf" attribute |
Organization Group | Organization | |
Clinician/Worker | Practitioner | |
Location | Location | |
Bed | Location | Connected to parent Location using "partOf" attribute |
Relationship | RelatedPerson | |
Diagnosis | Condition | |
Program | EpisodeOfCare | This is the Program as it relates to a Patient rather than the concept of the Program itself. |
Service Plan | CarePlan | |
Service Plan Goal | Goal | |
Service Plan Task | Task | |
Appointment | Appointment | |
Service Note | Procedure | |
Worker Team | CareTeam | I.e., the collection of Primary Worker, Secondary Worker, etc. as applicable. |
Agency Document | Questionnaire | I.e., the definition of an agency document |
Agency Document Response | QuestionnaireResponse | I.e., a specific administration of an Agency Document to a Client. |
Searching for Patients and Related Resources
Patient Resources are searchable by id, identifiers, and HumanNames using standard FHIR R4 search capabilities, which are supported by our FHIR services. Once a desired Patient Resource is identified, then all other FHIR resources related to that patient can be queried using a "_revinclude" search as follows:
GET [FHIR_HOST]/Patient?_id=[PersonGUID]&_revinclude=*
Including _revinclude=* in the search parameters will retrieve all Resource types related to the Patient. You can also return only specific related objects by specifying them by their resource type, like _revinclude=CareTeam.
Tips
-
We advise integrators to use conditional updates when creating new resources whenever there is a chance that the indicated resource may already exist so as to avoid unnecessary duplication. Conditional updates are designed to behave as follows:
-
If the requested Resource matches exactly one existing Resource, the existing resource will be updated with the supplied data.​
-
If the requested Resource matches no existing resource, the resource will be created as new.
-
If the requested Resource matches more than one existing resource, the operation will purposefully fail.
-
-
This documentation will be continually expanded to to provide guidance on specific FHIR Resource mappings and guidance for solving specific common use cases. However, it is always possible to simply "GET" an existing Resource and compare that to its representation in the CCL UI to deduce how specific object elements in the CCL EHR map to specific Resource attributes in our FHIR service.​