Working with FHIR
Fast Healthcare Interoperability Resources (FHIR) is a widely used health IT data standard for exchanging healthcare data. The Entity Extraction API includes support for FHIR structured responses. This page provides a general overview of FHIR and a deep dive into how to access the FHIR response via API.
Use Case
The Entity Extraction API FHIR capability simplifies healthcare organization integrations by facilitating seamless communication and interoperability among all health IT systems within their organization. This output structure is ideal for organizations who leverage FHIR for data storage or retrieval or integrate with other health systems supporting the FHIR standard. The FHIR standard provides the following benefits:
- Interoperable communication
- Ease of Electronic Health Record (EHR) integration
- Efficient data exchange
By utilizing FHIR, any healthcare organization can achieve a significant improvement in data interoperability, leading to more efficient and patient-centered care delivery across its network.
API Usage
To access the FHIR-formatted response callers should provide an Accept header value of application/fhir+json. If this header is not set, the Entity Extraction API will return the default, non-FHIR JSON output structure.
Contact IMO Customer Support for FHIR API access.
curl
curl -X POST \
-H "Authorization: Bearer <AUTH_TOKEN>" \
-H "Accept: application/fhir+json" \
-H "Content-Type: application/json" \
-data "{'text': 'John Smith has a headache and reports pain in his left leg.'}"\
"https://api.imohealth.com/entityextraction/pipelines/imo-clinical-comprehensive"python
import requests
auth_token='<AUTH_TOKEN>'
headers = {'Authorization': 'Bearer ' + auth_token, 'Accept': 'application/fhir+json'}
data = {'text': 'John Smith has a headache and reports pain in his left leg.', 'preferences': {'type_filter': ['entities', 'relations']}}
response = requests.post(
url = https://api.imohealth.com/entityextraction/pipelines/imo-clinical-comprehensive
json = data,
headers = headers
)
print(response.json())Response
{
"resourceType": "Bundle",
"type": "transaction",
"link": [
{
"extension": [
{
"extension": [
{
"url": "response_payload",
"valueString": "IMO_JSON_REPONSE_AS_STRING"
}
],
"url": "http://imohealth.com/extensions"
}
],
"relation": "describes",
"url": "https://api.imohealth.com/entityextraction/imo-clinical-comprehensive"
}
],
"entry": [
{
"fullUrl": "urn:uuid:40495eb1-b0a3-4ae0-ba24-0a57164701f9",
"resource": {
"resourceType": "Patient"
},
"request": {
"method": "POST",
"url": "Patient"
}
},
{
"fullUrl": "urn:uuid:8bc67813-82be-481d-ae5b-268b840b9749",
"resource": {
"resourceType": "Condition",
"extension": [
{
"extension": [
{
"url": "offset",
"valueInteger": 69
},
{
"url": "length",
"valueInteger": 4
}
],
"url": "http://hl7.org/fhir/StructureDefinition/derivation-reference"
}
],
"code": {
"coding": [
{
"extension": [
{
"extension": [
{
"url": "confidence_score",
"valueString": "1.0"
}
],
"url": "http://imohealth.com/extensions"
}
],
"system": "http://imohealth.com/ontology/problem/",
"code": "lx_45536",
"display": "Headache"
},
{
"extension": [
{
"extension": [
{
"url": "map_type",
"valueString": "Preferred primary"
}
],
"url": "http://imohealth.com/extensions"
}
],
"system": "http://hl7.org/fhir/sid/icd-9-cm",
"code": "784.0"
},
{
"extension": [
{
"extension": [
{
"url": "map_type",
"valueString": "Preferred primary"
}
],
"url": "http://imohealth.com/extensions"
}
],
"system": "http://hl7.org/fhir/sid/icd-10-cm",
"code": "R51.9"
},
{
"extension": [
{
"extension": [
{
"url": "map_type",
"valueString": "Preferred primary"
}
],
"url": "http://imohealth.com/extensions"
}
],
"system": "http://snomed.info/sct",
"code": "25064002"
}
],
"text": "headache"
},
"subject": {
"reference": "urn:uuid:40495eb1-b0a3-4ae0-ba24-0a57164701f9"
}
},
"request": {
"method": "POST",
"url": "Condition"
}
}
]
}For a more comprehensive schema, see the Reference Documentation at https://developer.imohealth.com/api-catalog/entity-extraction
Understanding the Response
Note: This API response currently supports HL7 FHIR version R4.
Transaction Bundle
The Entity Extraction API returns a FHIR Transaction Bundle. The transaction bundle includes actions to be performed on a set of resources identified by the API. This allows the system processing the transaction to perform these actions in a single HTTP request against their server.
Resource Types
The FHIR transaction bundle includes the following FHIR resource types:
| FHIR Resource | Description | Supported Fields |
|---|---|---|
| Patient | A placeholder patient resource, used to link all other identified resources together. | identifier - see Providing a Patient Identifier |
| Condition | Conditions identified within the input text by the API. | codeseveritybodySitesubject - links to the Patient resource in the bundle |
Additional resource types may be included in the future.
Resource References
Many returned resources in the FHIR response include references to other resources within the bundle. As IMO operates as a third party vendor building the FHIR resources on our client's behalf, we do not have access to literal references to actual database resources (e.g. a unique url identifying a patient in a hospital database). Therefore, we provide resources references as logical references, leveraging placeholder UUIDs and logical identifiers that resolve within the transaction. Placeholder UUIDs are generated by the API and associated with each bundle entry's fullUrl field. These UUIDs are temporary and only serve as links between resources in the transaction. When processing the transaction, it is up to the server to replace any logical references with literal URLs to actual known resources or generate new unique IDs within the server for brand new resources.
Providing a Patient Identifier
If a patient identifier is provided on the request, the corresponding bundle entry is constructed as a conditional create, as outlined in the HL7 documentation.
To provide a patient identifier, provide the following optional metadata fields on your request:
patient_identifier_system: The namespace for the patient identifierpatient_identifier_value: The unique value identifying the patient within the given system
Example request
{
"text": "John Smith has a headache and reports pain in his left leg.",
"metadata": {
"patient_identifier_system": "https://my-hospital",
"patient_identifier_value": "1234"
}
}Resulting patient bundle entry
{
"fullUrl": "urn:uuid:2b01068e-d9c8-4454-b91e-f49898d9ec65",
"resource": {
"resourceType": "Patient",
"identifier": [
{
"system": "https://my-hospital",
"value": "1234"
}
]
},
"request": {
"method": "POST",
"url": "Patient",
"ifNoneExist": "Patient?identifier=https://my-hospital|1234"
}
}Notices
©️ 2024 Intelligent Medical Objects, Inc. All Rights Reserved.
CPT®️ copyright 2023 American Medical Association. All rights reserved.
SNOMED®️ and SNOMED CT®️ are registered trademarks of IHTSDO.
LOINC®️ is a registered United States trademark of Regenstrief Institute Inc.
RxNorm is publicly available data courtesy of the U.S. National Library of Medicine (NLM), National Institutes of Health, Department of Health and Human Services.