End Points and FHIR R4 API

Parameters
response_type	required	Fixed value: code.
client_id	required	The client's identifier.
redirect_uri	required	Must match one of the client's pre-registered redirect URIs.
launch	conditional	When using the EHR Launch flow, this must match the launch value received from the EHR. Omitted when using the Standalone Launch.
scope	required	Must describe the access that the app needs, including scopes like patient/*.rs, openid and fhirUser (if app needs authenticated patient identity) and either: a launch value indicating that the app wants to receive already-established launch context details from the EHR a set of launch context requirements in the form launch/patient, which asks the EHR to establish context on your behalf. See SMART on FHIR Access Scopes details.
state	required	An opaque value used by the client to maintain state between the request and callback. The authorization server includes this value when redirecting the user-agent back to the client. The parameter SHALL be used for preventing cross-site request forgery or session fixation attacks. The app SHALL use an unpredictable value for the state parameter with at least 122 bits of entropy (e.g., a properly configured random uuid is suitable).
aud	required	URL of the EHR resource server from which the app wishes to retrieve FHIR data. This parameter prevents leaking a genuine bearer token to a counterfeit resource server. (Note that in the case of an EHR launch flow, this aud value is the same as the launch's iss value.) Note that the aud parameter is semantically equivalent to the resource parameter defined in RFC8707.
code_challenge	required	This parameter is generated by the app and used for the code challenge, as specified by PKCE.See considerations-for-pkce-support.
code_challenge_method	required	Method used for the code_challenge parameter. Example value: S256. See considerations-for-pkce-support.

Errors: See Error codes Here!

No Results: Returned as a Bundle of 4101 Error

Headers: We look at the Accept Header to determine response type.

To get a JSON response please only pass application/json.

For XML response please only pass application/xml. The default is XML.

Enabledoc FHIR R4 Interface Specification

Patient

Patient Interface

Patient Search

To perform a Patient Search you will need the patient’s FirstName, LastName and Date of Birth.

Requests without all these values will return no results.

The endpoint will be: [BaseURL]/Patient?family=[LastName]&given=[FirstName]&birthdate=[DOB(yyyyMMdd)]

A successful search will return a bundle of Patient with direct links to the patient based on the ID value.

To retrieve a specific patient by ID you will use the end point [BaseURL]/Patient/[ID] or alternately, you can use [BaseURL]/Patient?_id=[ID]

This ID Value will be used to retrieve all other Patient specific data.

Parameter Name	Parameter Type	Description
_id	Reference	Search for Patient resources using one or more server ids (equivalent to one or more Get /Patient/{ID} requests). If _id is included in your search, all other parameters are ignored.
identifier	Token	Search for Patient resources using a business identifier, such as an MRN. Queries must be in the format [OID]\|[ID], where [OID] is the HL7 Root of the identifier type, and is found in the Identifier.System field of a resource. You can use this parameter as the only parameter in a search or with other parameters.
family	String	name parameter, but do not need any other additional parameters.
given	String	Search for Patient resources using a first name or given name. This parameter is used to find patients with matching given names, and supports both exact and “sounds like” matches. Query responses return matching patients in order of closest match, with the strongest match first. You must use this parameter with the family parameter, but do not need any additional parameters.
birthdate	Date	Search for Patient resources using a date of birth in XML format (YYYY-MM-DD). You must use this parameter with one of the following sets of parameters: identifier, telecom, or family and given
gender	Token	Search for Patient resources using the following gender codes: female, male, other, or unknown. You must use this parameter with one of the following sets of parameters: identifier , telecom, or family and given.
address	String	Search for Patient resources using an address string.Queries must be formatted as a string and only contain the first line of the patient's street address. You must use this parameter with one of the following parameters: identifier, telecom, or family and given.
telecom	String	Search for Patient resources using a patient’s home or cell phone number. Queries can be formatted with or without dashes. You can use this parameter as the only parameter in a search or with other parameters.

Patient

Patient follows ONC's by USCDI version 1.requirements, each Patient must support the following additional elements. The patient examples include all of these elements:

contact detail (e.g. a telephone number or an email address)
a communication language
a race
an ethnicity
a birth sex*
previous name
Suffix
Current Address
Prior Address

Patient Response is defined by USCDI version 1.

Patient XML Example Response

<meta>

</extension>

<extension

url="http://hl7.org/fhir/StructureDefinition/instance-description">

<valueMarkdown

value="This is a patient example for the *US Core Patient Profile*."/>

</extension>

<profile

value="http://hl7.org/fhir/us/core/StructureDefinition/us-core-patient"/>

</meta>

<text>

<div xmlns="http://www.w3.org/1999/xhtml">Generated Narrative<blockquote>US Core Race Extensionvalue: Whitevalue: American Indian or Alaska Nativevalue: Asianvalue: Shoshonevalue: Filipinovalue: Mixed</blockquote><blockquote>US Core Ethnicity Extensionvalue: Hispanic or Latinovalue: Dominicanvalue: Mexicanvalue: Hispanic or Latino</blockquote>US Core Birth Sex Extension: Fidentifier: Medical Record Number: 1032702 (USUAL)active: truename: Amy V. Shaw , Amy V. Baxter telecom: ph: 555-555-5555(HOME), <a href="mailto:amy.shaw@example.com">amy.shaw@example.com</a>gender: femalebirthDate: 1987-02-20address: <ul><li>49 Meadow St Mounds OK 74047 US </li><li>183 Mountain View St Mounds OK 74048 US </li></ul></div>

</text>

</valueCoding>

</extension>

</valueCoding>

</extension>

</valueCoding>

</extension>

</valueCoding>

</extension>

</valueCoding>

</extension>

</extension>

<extension

url="http://hl7.org/fhir/us/core/StructureDefinition/us-core-ethnicity">

</valueCoding>

</extension>

</valueCoding>

</extension>

</valueCoding>

</extension>

</extension>

<extension

url="http://hl7.org/fhir/us/core/StructureDefinition/us-core-birthsex">

</extension>

<type>

</coding>

</type>

</identifier>

<name>

</period>

</name>

<name>

</period>

</name>

</telecom>

</telecom>

</period>

</address>

</period>

</address>

</Patient>

Provenance

Provenance requests describe authors, entities, and times and date stamps associated with a process or clinical data. Provenance supports US.Core Procedure Profile.

Relative URL	FHIR Interaction	HTTP Method	Action

/Provenance/{ID string}	Read	Get	Provenance FHIR ID.ID

Parameter Name	Parameter Type	Description

_id	Token	The logical resource id associated with the resource.
target	reference	Target Reference(s) (usually version specific). The AllergyIntolerance, CarePlan, CareTeam, Condition, DiagnosticReport, DocumentReference, Encounter, Goal, Immunization, MedicationRequest, Observation (all vitals), Patient, and Procedure resources are supported.

The following fields are returned if correct valued:

Provenance id - FHIR Id
Target The resource that the provenance describes
Recorded - Date and time activity was created or updated
Agent type - Author of transmitter
Agent role - Source of informant
Agent who - Name of practitioner, organization, or device
Agent on behalf of - Agent or staff on behalf of practitioner

AllergyIntolerance Provenance XML Example Response

<meta>

</extension>

<extension

url="http://hl7.org/fhir/StructureDefinition/instance-description">

<valueMarkdown

value="This is a allergyintolerance provenance example for the *Bundle Profile*."/>

</extension>

</meta>

<link>

<url

value="http://example.org/fhir/AllergyIntolerance?_revinclude=Provenance%3Atarget&patient=Examples"/>

</link>

<entry>

<meta>

<profile

value="http://hl7.org/fhir/us/core/StructureDefinition/us-core-allergyintolerance"/>

</meta>

<text>

<div xmlns="http://www.w3.org/1999/xhtml">Generated NarrativeclinicalStatus: ActiveverificationStatus: Confirmedcategory: medicationcriticality: highcode: Peanutspatient: <a href="Patient-example.html">Generated Summary: Medical Record Number: 1032702 (USUAL); active; Amy V. Shaw , Amy V. Baxter ; Phone: 555-555-5555, amy.shaw@example.com; gender: female; birthDate: 1987-02-20</a>onset: 2017-06-09<h3>Reactions</h3><table class="grid"><tr><td>-</td><td>Manifestation</td><td>Onset</td></tr><tr><td>*</td><td>Hives</td><td>2017-06-09</td></tr></table></div>

</text>

<system

value="http://terminology.hl7.org/CodeSystem/allergyintolerance-clinical"/>

</coding>

</clinicalStatus>

<system

value="http://terminology.hl7.org/CodeSystem/allergyintolerance-verification"/>

</coding>

</verificationStatus>

<code>

</coding>

</code>

</patient>

</coding>

</manifestation>

</reaction>

</AllergyIntolerance>

</resource>

</search>

</entry>

<entry>

<meta>

<profile

value="http://hl7.org/fhir/us/core/StructureDefinition/us-core-provenance"/>

</meta>

<text>

<div xmlns="http://www.w3.org/1999/xhtml">Generated Narrativetarget: <a href="#AllergyIntolerance_79613">See above (AllergyIntolerance/79613)</a>recorded: Jul 9, 2019 3:26:23 PM<h3>Agents</h3><table class="grid"><tr><td>-</td><td>Type</td><td>Who</td><td>OnBehalfOf</td></tr><tr><td>*</td><td>Author</td><td><a href="Practitioner-practitioner-1.html">Generated Summary: id: 9941339108, id: 25456; Ronald Bone </a></td><td><a href="Organization-saint-luke-w-endpoint.html">Generated Summary: id: 1063494177, id: 00-0000000; active; name: Saint Luke's Hospital of Kansas City; Phone: (816)932-2000, </a></td></tr></table></div>

</text>

</target>

<agent>

<type>

<system

value="http://terminology.hl7.org/CodeSystem/provenance-participant-type"/>

</coding>

</type>

<who>

</who>

</onBehalfOf>

</agent>

</Provenance>

</resource>

</search>

</entry>

</Bundle>

Practitioner

Practitioner (proider) search allows provider names, address and phone number to be retrieved. This resource is referenced by AllergyIntolerance, CarePlan, CareTeam, Condition, DiagnosticReport, DocumentReference, Encounter, Immunization, MedicationRequest, MedicationStatement, Observation, Patient, Procedure, and Provenance.

US Core Practitioner Profile for Practitioners

Relative URL	FHIR Interaction	HTTP Method	Action
/Practitioner/{ID}	Read	Get	Retrieve practitioner by ID

Parameter Name	Parameter Type	Description

_id	Token
name	string	A server defined search that may match any of the string fields in the HumanName, including family, give, prefix, suffix, suffix, and/or text
phone	token	A phone number

Practitioner XML Example Response

<?xml version="1.0" encoding="UTF-8"?>

<text>

Dr Adam Careful is a Referring Practitioner for Acme Hospital from 1-Jan 2012 to 31-Mar

2012

</div>

</text>

</identifier>

<name>

</name>

</address>

</identifier>

<code>

</coding>

</code>

</period>

</issuer>

</qualification>

</Practitioner>

MedicationsRequest

This will allow prescribed or ordered medications to be retrieved.

Each MedicationRequest must have:

a status
an intent code
a medication*
a patient
a prescriber

Each MedicationRequest must support:

the category (e.g. Discharge Medication)
the reported flag or reference signaling that information is from a secondary source such as a patient
the encounters
a date for when written
the prescription Sig

Must adhere to US Core Medications Request Profile.

MedicationRequest Filter Parameters

Relative URL	FHIR Interaction	HTTP Method	Action
/MedicationRequest?[parameter=value]	Search	Get	Retrieves all medications for a given patient

Parameter Name	Parameter Type	Description

patient	Reference	Retrieve MedicationRequest by patient ID.
status	Token	Filter prescriptions by active, completed, stopped, and non-active status.
dateWritten	Date	Filter prescriptions list by the date the prescription was written.
MedicationRequest.category:us-core	Token	Select options of inpatient, outpatient, community, and discharge.
MedicationRequest.priority	Token	Select options of stat, routine, urgent, asap

MedicationRequest XML Example Response

<?xml version="1.0" encoding="UTF-8"?>

<text> <status value="generated"/> <div xmlns="http://www.w3.org/1999/xhtml"> Generated Narrative <div style="display: inline-block; background-color: #d9e0e7; padding: 6px; margin: 4px; border: 1px

solid #8da1b4; border-radius: 5px; line-height: 60%">Resource "medrx002" </div> identifier : id: 12345 (OFFICIAL) status : active intent : order medication : <a href="medication-med0316.html">Medication/med0316: prescribed medication</a> subject : <a href="patient-pat1.html">Patient/pat1: Donald Duck</a> "Duck DONALD" encounter : <a href="encounter-f001.html">Encounter/f001: encounter that leads to this prescription</a> authoredOn : 2015-03-01 requester : <a href="practitioner-f007.html">Practitioner/f007: Patrick Pump</a> "Simone HEPS" reasonCode : Essential hypertension (disorder) (<a href="https://browser.ihtsdotools.org/">SNOMED CT</a> #59621000) </div> </text> <identifier>

</identifier>

</medicationReference>

</subject>

</encounter>

</requester>

</coding>

</reasonCode>

</dosageInstruction>

</MedicationRequest>

Medications

This will allow you to retrieve both the prescriptions (MedicationOrder) and current medications (MedicationStatement) for a patient. The FHIR MedicationOrder includes prescriptions or OTC drugs ordered by the provider.with the medication script.

The FHIR MedicationStatement function defines detailed information about medications being taken by the patient. This includes medication prescriptions, OTC drugs ordered, and current medications reported taken by a patient. US Core Medications Request Profile.

MedicationRequest

Relative URL	FHIR Interaction	HTTP Method	Action
/MedicationRequest?[parameter=value]	Search	Get	Retrieves all medications for a given patient

Parameter Name	Parameter Type	Description

patient	Reference	Retrieve MedicationOrder by patient ID.
status	Token	Filter prescriptions by active, completed, stopped, and non-active status.
dateWritten	Date	Filter prescriptions list by the date prescription was written.

Examples

Query	Result
/MedicationRequest?patient=24E2B196-55A9-4041-BD89-2D025B9E5F32	Returns all active medications resources for Alice Newman
/MedicationRequest?patient=24E2B196-55A9-4041-BD89-2D025B9E5F32&status=active,completed	Returns active and completed MedicationOrder resources for Alice Newman

MedicationOrder Read Interaction

Relative URL	FHIR Interaction	HTTP Method	Action
/MedicationOrder/{ID}	Read	Get	Retrieve MedicationOrde by ID

MedicationStatement Search Interaction

Relative URL	FHIR Interaction	HTTP Method	Action
/MedicationStatement?[parameter=value]	Search	Get	Retrieves current medications

Parameter Name	Parameter Type	Description
patient	Reference	Retrieve data by patient ID.
status	Token	Status of active, completed, intended, and non activated to filter the list of current medications.
effectiveDate	Date	Retrieves current medications list by the effective date.

Examples

Query

Result

/MedicationStatement?patient=24E2B196-55A9-4041-BD89-2D025B9E5F32

Returns all active current meds for Alice Neman

/MedicationStatement?patient=24E2B196-55A9-4041-BD89-2D025B9E5F32&status=active,completed

Returns active and completed MedicationStatement resources for Jason Argonaut.

Medication XML Example Response

<?xml version="1.0" encoding="UTF-8"?>

<text> <status value="generated"/> <div xmlns="http://www.w3.org/1999/xhtml"> Generated Narrative with Details id : med0310 contained : code : Oral Form Oxycodone (product) (Details : {SNOMED CT code '430127000' = 'Oral form oxycodone', given as 'Oral Form Oxycodone

(product)'}) form : Tablet dose form (qualifier value) (Details : {SNOMED CT code '385055001' = 'Tablet', given as 'Tablet dose form (qualifier

value)'}) <h3> Ingredients</h3> <table> <tr> <td> -</td> <td> Item[x] </td> <td> Strength </td> </tr> <tr> <td> *</td> <td> id: sub03; Oxycodone (substance) (Details : {SNOMED CT code '55452001' = 'Oxycodone', given as 'Oxycodone (substance)'}) </td> <td> 5 mg (Details: UCUM code mg = 'mg') /1 TAB (Details: http://terminology.hl7.org/CodeSystem/v3-orderableDrugForm code TAB = 'Tablet') </td> </tr> </table> </div> </text> <contained>

<code>

</coding>

</code>

</Substance>

</contained>

<code>

</coding>

</code>

<form>

</coding>

</form>

</itemReference>

</numerator>

</denominator>

</strength>

</ingredient>

</Medication>

Allergies

This will allow you to retrieve known allergies for a patient. The FHIR AllergyIntolerance resource defines clinical information about a patient's allergic response to a substance. The AllergyIntolerance resource displays the substance reacted to, level of severity, type of reaction, and onset date.

AllergyIntolerance Search Interaction

Relative URL	FHIR Interaction	HTTP Method	Action
/AllergyIntolerance?[parameter=value]	Search	Get	Retrieve AllergyIntolerance using the specified search criteria.

Parameter Name	Parameter Type	Description
patient	Reference	Search for AllergyIntolerance resources by patient ID.
onset	Date	Further refine a search for AllergyIntolerances by onset date

AllergyIntolerance Read Interaction

Relative URL

FHIR Interaction

HTTP Method

Action

/AllergyIntolerance/{ID}

Read

Get

Retrieve details about AllergyIntolerance ID

Condition

The Condition function is retrieves a patient’s problems, diagnoses, or other health concerns during the encounter or visit. Conditions are typically associated with other resources, such as the reason for a prescription, procedure, diagnostic test, etc... A Condition might be acute or chronic, but it is not used to represent an adverse reaction or an allergy intolerance.

Search Interaction

Relative URL	FHIR Interaction	HTTP Method	Action
/Condition?[param=value]	Search	Get	Retrieve Condition function using the specified search criteria.

Parameter Name	Parameter Type	Description
patient	Reference	Search for Condition function by a patient ID.
category	Token	Indicates the type of Condition resource associated with the patient. The standard FHIR category code of diagnosis, along with the Extension Codes defined by the Argonaut project of problem and health-concern are supported as options.
clinicalStatus	Token	Further refine a search for Conditions by providing a status of the condition. By default, confirmed Condition resources are returned. Statuses of confirmed and resolved are supported.
onset	Date	Further refine a search for Conditions by providing by specifying a date or range of dates for when the condition first affected the patient. Note: all active conditions will be returned in the response in addition to other data returned in the search.

Examples

Query	Result
/Condition?patient=24E2B196-55A9-4041-BD89-2D025B9E5F32	Returns all Conditions for Alice Newman
/Condition?patient=24E2B196-55A9-4041-BD89-2D025B9E5F32&category=diagnosis&clinicalStatus=resolved	Returns all resolved Conditions for Alice Newma
/Condition?patient=24E2B196-55A9-4041-BD89-2D025B9E5F32&category=health-concern	Returns all Conditions for Alice Newman of category healthConcern

Observations

The FHIR Observation function defines information about a measurement, observation, or test results about a patient. The below documentation describes how the Observation resource is used to:

Provide measurements gathered as a vital sign or flowsheet data point.
Describe analyte level result information or sensitivities and isolates from a microbiology analysis.
Retrieve the patient's current smoking status.

Examples of common observations are: Laboratory results (blood sugar, hemoglobin), Vital signs (temperature, blood pressure), Personal characteristics (height, weight), and Social history (tobacco/alcohol use, employment status).

List of profiles we support:

Observation Search Interaction

Relative URL	FHIR Interaction	HTTP Method	Action
/Observation?[parameter=value]	Search	Get	Retrieves Observation function that meet the specified search criteria

Parameter Name	Parameter Type	Description
patient	Reference	Search for Observation function for a specified patient ID. Both patient and code or category are required for a valid patient-based search.
code	Token	Search for Observation function for a valid LOINC code. Both patient and code (or category) are required for a valid patient-based search.
category	Token	Search for Observation function for a valid category (vital-signs, social-history, laboratory). Both patient and category (or code) are required for a valid patient-based search.
Status	Token	Status options of preliminary, final, canceled, and unknown
date	Date	Further refine a search for a given set of result- or vital sign-based Observations by specifying a date or date range in XML format (YYYY-MM-DD) for when the observation was resulted or recorded.
issued	Date	Further refine a search for a smoking history Observations by specifying a date or date range in XML format (YYYY-MM-DD) for when the observation was recorded.

Examples

Query	Result
/Observation?patient=24E2B196-55A9-4041-BD89-2D025B9E5F32&code=8310-5	Returns all temperature (8310-5) Observations for Alcie Newman.
/Observation?patient=24E2B196-55A9-4041-BD89-2D025B9E5F32&code=3141-9&date=20150622	Returns all weight (3141-9) Observations for Alice Newman documented on June 22, 2015.
/Observation?patient=24E2B196-55A9-4041-BD89-2D025B9E5F32&code=1975-2	Returns all bilirubin (1975-2) Observations for Jason Argonaut.
/Observation?patient=24E2B196-55A9-4041-BD89-2D025B9E5F32&code=718-7&date=lt20190101	Returns all hemoglobin (718-7) Observations for Alice Newman resulted prior to 2019.
/Observation?patient=24E2B196-55A9-4041-BD89-2D025B9E5F32&code=72166-2	Returns the current Smoking History status (72166-2) Observation for Alice Newman

Observation Read Interaction

Relative URL

FHIR Interaction

HTTP Method

Action

/Observation/{ID}

Read

Get

Retrieve details about Observation ID

Lab Results

Each Observation must have:

a status
a category code of ‘laboratory’
a LOINC code, if available, which tells you what is being measured
a patient

Each Observation must support:

a time indicating when the measurement was taken
a result value or a reason why the data is absent*

if the result value is a numeric quantity, a standard UCUM unit

DiagnosticReport

Retrieves radiology diagnostic reports.The FHIR DiagnosticReport function contains information about a single diagnostic service performed for a patient. Individual components and text-based content, such as narratives or impressions, are represented within the DiagnosticReport with a FHIR Observation resource.

DiagnosticReport Search Interaction

Relative URL	FHIR Interaction	HTTP Method	Action
/DiagnosticReport?[parameter=value]	Search	Get	Retrieves DiagnosticReport function that meet the specified search criteria

Parameter Name	Parameter Type	Description
patient	Reference	Search for DiagnosticReport function by patient ID.
date	Date	Filter DiagnosticReports for a patient by specifying a date or date range in XML format (YYYY-MM-DD) for when the DiagnosticReport was resulted.

DiagnosticReport Examples

Query	Result
/DiagnosticReport?patient=24E2B196-55A9-4041-BD89-2D025B9E5F32	Retrieve all Diagnostic Reports for Alice Newman
DiagnosticReport?patient=24E2B196-55A9-4041-BD89-2D025B9E5F32&date=gt2016-02-01&date=lt2015-05-22	Retrieve all Diagnostic Reports for Jason Argonaut resulted in June, 22 2015

DiagnosticReport Read Interaction

Relative URL

FHIR Interaction

HTTP Method

Action

/DiagnosticReport/{ID}

Read

Get

Retrieve details about DiagnosticReport ID

DocumentReference

Retrieves clinical notes and reports for six different categories.

DocumentReference Search Interaction

Relative URL	FHIR Interaction	HTTP Method	Action
/DiagnosticReport?[parameter=value]	Search	Get	Retrieves DiagnosticReport function that meet the specified search criteria

Parameter Name	Parameter Type	Description
patient	Reference	Search for Document Reference function by patient ID.
date	Date	Filter Document Reference for a patient by specifying a date or date range in XML format (YYYY-MM-DD) for when the Document was created.

DiagnosticReport Examples

Query	Result
/DocumentRefrence?patient=24E2B196-55A9-4041-BD89-2D025B9E5F32	Retrieve all Document Reference for Alice Newman
DocumentReference?patient=24E2B196-55A9-4041-BD89-2D025B9E5F32&date=gt2016-02-01&date=lt2015-05-22	Retrieve all Document Reference for Jason Argonaut resulted in June, 22 2015

DocumentReference Read Interaction

Relative URL

FHIR Interaction

HTTP Method

Action

/DocumentReference/{ID}

Read

Get

Retrieve files associated with the DocumentReferenceID

Immunization Records

This will allow you to retrieve immunizations administered and Immunization history for a patient.

Immunization Search Interaction

Relative URL	FHIR Interaction	HTTP Method	Action
/Immunization?[parameter=value]	Search	Get	Retrieves Immunization function that meet the specified search criteria

Parameter Name	Parameter Type	Description
patient	Reference	Search for Immunization resources for a specified patient ID.
date	Date	Further refine a search for a given set of Immunizations on a patient by specifying a date or date range in XML format (YYYY-MM-DD) for when the Immunization was administered or last documented.

Immunization Examples

Query	Result
/Immunization?patient=24E2B196-55A9-4041-BD89-2D025B9E5F32	Retrieve Immunization resources for Alice Newman.
/Immunization?patient=24E2B196-55A9-4041-BD89-2D025B9E5F32&date=gt2015-06-01	Retrieve Immunization resources for Alice Newman administered after June 1, 2015

Immunization Read Interaction

Relative URL

FHIR Interaction

HTTP Method

Action

/Immunization/{ID}

Read

Get

Retrieve details about Immunization ID

Encounters

The FHIR Encounter functionenables encounter specific clinical data to be retrieved.

Procedure Search Interaction

Relative URL	FHIR Interaction	HTTP Method	Action
/Encounter?[parameter=value]	Search	Get	Retrieves Encounter data

Procedures

The FHIR Procedure function retrieves surgeries and procedures performed, including endoscopies and biopsies, as well as less invasive actions like counseling and physiotherapy.

Procedure Search Interaction

Relative URL	FHIR Interaction	HTTP Method	Action
/Procedure?[parameter=value]	Search	Get	Retrieves Procedure function that meet the specified search criteria

Parameter Name	Parameter Type	Description
patient	Reference	Search for Procedure function by patient ID.
date	Date	Further refine a search for a given set of Procedures on a patient by specifying a date or date range in XML format (YYYY-MM-DD) for when the Procedure was resulted.

Examples

Query	Result
/Procedure?patient=24E2B196-55A9-4041-BD89-2D025B9E5F32	Retrieve all Procedures for Alice Newman.
/Procedure?patient=24E2B196-55A9-4041-BD89-2D025B9E5F32&date=gt2015-12-31	Retrieve all Procedures for Alice Newman in 2015.

Procedure Read Interaction

Relative URL

FHIR Interaction

HTTP Method

Action

/Procedure/{ID}

Read

Get

Retrieve details about Procedure ID

Implanted Devices

This will allow you to retrieve a list of implanted devices installed in patient.

The FHIR Device resource describes information about a specific patient's durable, manufactured medical items. The below documentation describes only medical devices implanted in a patient.

Device Search Interaction

Relative URL	FHIR Interaction	HTTP Method	Action
/Device?[parameter=value]	Search	Get	Retrieves Device function that meet the specified search criteria

Parameter Name	Parameter Type	Description
patient	Reference	Search for Device resources for a specified patient ID.
type	Token	further filter devices for a given patient by restricting the results of a search to one or more device types.
udi	String	Further refine a search for a Devices by restricting the results of a search to one or more device udis as described by the device's FDA-mandated Universal Device Identifier.
_lastUpdated	Date	Further refine a search for a Devices by specifying a date or range of dates. Note: all currently implanted devices for the patient will be included in the response in addition to other results returned in the search.

Examples

Query	Result
/Device?patient=24E2B196-55A9-4041-BD89-2D025B9E5F32	Retrieve all implanted devices documented for Alice Newman
/Device?patient=24E2B196-55A9-4041-BD89-2D025B9E5F32&type=Pacemaker	Retrieve all implanted devices documented for Alice Newman which are of type "Pacemaker".

Device Read Interaction

Relative URL

FHIR Interaction

HTTP Method

Action

/Device/{ID}

Read

Get

Retrieve details about Device ID

Binary -CDA Document Retrieval

This will allow you to retrieve a CDA clinical summary document (CCDA 2.1) for a patient. The FHIR DocumentReference resource describes information about a document. The DocumentReference resource includes information about a document, the associated patient and author, and information about its creation. The DocumentReference function only contains metadata about the document. The actual document content is accessed via the Binary resource that is referenced in DocumentReference.content.attachment.url.

The FHIR Binary resource is the rendering of any FHIR resource with different native file types in XML or JSON. The below documentation describes the use of the Binary resource to retrieve CDA documents via FHIR API.

DocumentReference Search Interaction

Relative URL	FHIR Interaction	HTTP Method	Action
/DocumentReference?[parameter=value]	Search	Get	Retrieves DocumentReference function that meet the specified search criteria

Parameter Name	Parameter Type	Description
patient	Reference	Search for DocumentReference function by patient ID.
created	Date	Filter by a date or date range in XML format (YYYY-MM-DD) for when the DocumentReference was created.
class	Token	Further refine a search for a given set of DocumentReferences on a patient by specifying a document class to return only documents of that type.

Examples

Query	Result
/DocumentReference?patient=24E2B196-55A9-4041-BD89-2D025B9E5F32	Retrieve all DocumentReference resources for Alice Newman
/DocumentReference?patient=24E2B196-55A9-4041-BD89-2D025B9E5F32&created=2015-05-22	Retrieve all DocumentReference resources for Alice Newman created on June 22, 2015.

DocumentReference Read Interaction

Relative URL

FHIR Interaction

HTTP Method

Action

/DocumentReference/{ID}

Read

Get

Retrieve details about DocumentReference ID

Goal

Retrieve the patients goals to improve health, track status and set due dates.

Goal Read

Relative URL

FHIR Interaction

HTTP Method

Action

/Goal/{ID}

Read

Get

Retrieve details about Goal ID

Goal XML Example Response

<?xml version="1.0" encoding="UTF-8"?>

<text>

A simple care goal for a patient to lose weight due to obesity.

</div>

</text>

</identifier>

</coding>

</category>

</coding>

</priority>

</description>

</subject>

</coding>

</measure>

<low>

</low>

<high>

</high>

</detailRange>

</target>

</expressedBy>

</addresses>

</outcomeReference>

</Goal>

Care Plan

Retrieve a patient’s longitudinal Care Plan health concerns and goals. The FHIR CarePlan function is a comprehensive Plan of Care that spans providers and specialties to display a complete summary of health concerns, goals, instructions, interactions, and outcomes.

CarePlan Search Interaction

Relative URL	FHIR Interaction	HTTP Method	Action
/CarePlan?[parameter=value]	Search	Get	Retrieves CarePlan function that meet the specified search criteria

Parameter Name	Parameter Type	Description
patient	Reference	Search for CarePlan resources for a specified patient ID.
date	Date	Further refine the content within the CarePlan by providing by specifying a date or range of dates for what historical data should be included in the care plan. Note: all active historical data and all future data will be returned in the response in addition to other data returned in the search.
category	Token	Further refine which CarePlan resources are returned by category. There are two supported categories: 38717003 will return only the longitudinal care plan. 734163000 will return encounter-level care plans. If no category is specified, only the longitudinal care plan is returned.

Care Plan XML Example Response

"resourceType": "Bundle",

"id": "bfa30a51-3eab-471c-948c-e8b93ff988d9",

"meta": {

"lastUpdated": "2022-11-09T10:13:09.555+00:00"

"type": "searchset",

"total": 6,

"link": [

{

"relation": "self",

"url": "https://inferno.healthit.gov/reference-server/r4/CarePlan?category=assess-plan&patient=85"

}

"entry": [

{

"fullUrl": "https://inferno.healthit.gov/reference-server/r4/CarePlan/149",

"resource": {

"resourceType": "CarePlan",

"id": "149",

"meta": {

"versionId": "1",

"lastUpdated": "2021-03-23T19:36:17.299+00:00",

"source": "#E1VolYkq84D3M96u",

"profile": [

"http://hl7.org/fhir/us/core/StructureDefinition/us-core-careplan"

]

"text": {

"status": "generated",

"div": "<div xmlns=\"http://www.w3.org/1999/xhtml\">Care Plan for Fracture care. Activities: <ul><li>Fracture care</li><li>Fracture care</li></ul> Care plan is meant to treat Fracture of clavicle.</div>"

"status": "completed",

"intent": "order",

"category": [

{

"coding": [

{

"system": "http://hl7.org/fhir/us/core/CodeSystem/careplan-category",

"code": "assess-plan"

}

]

{

"coding": [

{

"system": "http://snomed.info/sct",

"code": "385691007",

"display": "Fracture care"

}

"text": "Fracture care"

}

"subject": {

"reference": "Patient/85"

"encounter": {

"reference": "Encounter/145"

"period": {

"start": "1946-11-23T01:11:45-05:00",

"end": "1947-01-22T01:11:45-05:00"

"careTeam": [

{

"reference": "CareTeam/148"

}

"addresses": [

{

"reference": "Condition/146"

}

"activity": [

{

"detail": {

"code": {

"coding": [

{

"system": "http://snomed.info/sct",

"code": "183051005",

"display": "Recommendation to rest"

}

"text": "Recommendation to rest"

"status": "completed",

"location": {

"reference": "Location/103",

"display": "LOWELL GENERAL HOSPITAL"

}

{

"detail": {

"code": {

"coding": [

{

"system": "http://snomed.info/sct",

"code": "408580007",

"display": "Physical activity target light exercise"

}

"text": "Physical activity target light exercise"

"status": "completed",

"location": {

"reference": "Location/103",

"display": "LOWELL GENERAL HOSPITAL"

}

]

"search": {

"mode": "match"

}

Binary -CDA Document Retrieval

The FHIR Binary resource is the rendering of any FHIR resource with different native filetypes in XML or JSON. The below documentation describes the use of the Binary resource to retrieve CDA documents via FHIR API.

Example: Binary-example.xml - FHIR v4.3.0 (hl7.org)

Bulk Data Export

The FHIR Bulk Export Service is designed to comply with the 21st Century Cures bulk data export requirements. This feature uses the FHIR API functions certified under the 2015 Edition CEHRT (g)(10) criterion. The FHIR Bulk Export service enables API developers to make asynchronous requests to export USCDI (United States Core Data for Interoperability) clinical data for shared patients by the approved group. With FHIR Bulk Export, you can retrieve data for multiple patients at a time. Our FHIR APIs are secured using OAuth scopes, which is requested in Developer Account via an approve application process.

The following authorization scopes and associated patients are supported in our implementation of FHIR Bulk Export:

system/AllergyIntolerance.read
system/CarePlan.read
system/CareTeam.read
system/Condition.read
system/Device.read
system/DiagnosticReport.read
system/DocumentReference.read
system/Encounter.read
system/Goal.read
system/Immunization.read
system/Location.read
system/Medication.read
system/MedicationRequest.read
system/Observation.read
system/Organization.read
system/Patient.read
system/Practitioner.read
system/Procedure.read
System/Provenance.read

Running Bulk Export

Bulk export authentication is performed as part of our Oauth 2.0 authentication. The detailed FHIR Bulk Export specification provides the details: FHIR Asynchronous Request Pattern:

1. Export get- GET/fhir/r4/Group/{logicalId}/$export

FHIR client makes an http GET request to initiate an export job (refer here for more details on Group-level export documentation).
Specify the following HTTP header values in your export request:

Prefer: respond-async
Accept: application/fhir+json

A polling URL containing the jobId is returned in the response Location header.

2. Export Status- GET/fhir/r4/$export-poll-status/{jobId}

FHIR client makes an http GET request for polling the job status.
Polling URL returns progress indicator in response header until the job is completed.

'X-Progress' which shows the percentage completed
'Retry-After' which indicates how long to wait before polling again

FHIR client continues polling the job status URL until the export job is 100% completed.
FHIR client downloads exported files using the Pre-Signed URLs returned in the response body of the polling URL (see example response body here).

3. Export Delete - DELETE/fhir/r4/$export-poll-status/{jobId}

FHIR client can cancel the export job at any time by making a DELETE request to the same polling location URL.

A more detailed sequence diagram of the workflow is also provided by HL7 here.

Additional Information

Exported files are hosted in a protected in AWS in .ndjson format.
Exported data will be available for download for 60 days after creation.
The URLs returned in the .ndjson file are URLs. These URLs are valid for a period of 1 hour (60 minutes) after manifest retrieval.
When polling for file status, or canceling a job, FHIR client must have a valid auth token with the same client ID as the one used to initiate the export job.

In the case of partial failure, the bulk export job completion results will contain an error file of OperationOutcome resources which include diagnostic strings that enumerate the list of patients which have failed in each task or the resources that failed for a patient.
We do not recommend using FHIR Bulk Export for real-time access needs, daily data synchronizations, or for single patient’s health information.