FHIR Observation
Base Path: /fhir/4.0/Observation
Version: 1.1.0
This API allows you to:
- Retrieve all Observation resources that match a search criteria for a given patient.
- Retrieve a specific Observation resource based on its FHIR ID.
- Retrieve the history of an Observation resource based on its FHIR ID. Note: history is not supported for CDR or Clinical Data Space sources.
- Retrieve a specific version of an Observation resource based on its FHIR ID.
- Retrieve a specific version of an Observation resource based on its FHIR ID and Version ID. Note: retrieval by version ID is not supported for CDR or Clinical Data Space sources.
- Supports exporting resources via FHIR Bulk.
The data returned in this API is subject to privacy and permissions settings, refer to the Working with Privacy guide to learn how this might affect your application.
The Observation API aggregates data from multiple sources, to learn about working with aggregated APIs refer to the Aggregated APIs guide in the Knowledge Hub.
This API is based on the R4 release of the FHIR standard, for more information on this API refer to the official FHIR documentation.
Methods
Retrieve Observations for a Patient
GET /fhir/4.0/Observation/
This method returns all observations for the patient identified by patient.identifier. Optionally filtering by the code, category, date, status and encounter of the observation.
Parameters
Name
Type
Data Type
Description
Name:
patient.identifier
required
Type:
query
Data Type:
string
Description:
The patient identifier consists of patient identifier namespace, also known as the system, and identifier, separated using a URL encoded | character i.e. %7c.
Note: You must either define the patient.identifier or patient or subject.identifier or subject, not a combination of those parameters.
Sample Value: ORION|AAAA-0124-8
Name:
subject.identifier
required
Type:
query
Data Type:
string
Description:
The patient identifier consists of patient identifier namespace, also known as the system, and identifier, separated using a URL encoded | character i.e. %7c.
Note: You must either define the patient.identifier or patient or subject.identifier or subject, not a combination of those parameters.
Sample Value: SYS_A|75849-3478
Name:
patient
required
Type:
query
Data Type:
string
Description:
The patient resource id. Note: You must either define the patient.identifier or patient or subject.identifier or subject, not a combination of those parameters.
Sample Value: IFAUCLJQGAYTIMRNGFAE6USJJ5HA
Name:
subject
required
Type:
query
Data Type:
string
Description:
The patient resource id. Note: You must either define the patient.identifier or patient or subject.identifier or subject, not a combination of those parameters.
Sample Value: IFAUCLJQGAYTIMRNGFAE6USJJ5HA
Name:
date
optional
Type:
query
Data Type:
array
Description:
Filters the observations to those with an effectiveDateTime or effectivePeriod on, before, or after a specific date, date-time, or date range.
The supported prefixes are gt, ge, lt, le and eq. If no prefix is used, exact date or date-time matching is implied.
Dates must be formatted according to ISO 8601 either as a date only (e.g. 1997-07-16) or as a date-time including the timezone (e.g. 1997-07-16T19:20:30+13:00).
Ensure that special characters such as + are URL encoded i.e. %2B.
The format of the query is
/Observation?patient.identifier={patientNamespace}|{patientIdentifier}&date=gt{dateTimeValue}/Observation?patient.identifier={patientNamespace}|{patientIdentifier}&date=ge{dateTimeValue}&date=le{dateTimeValue}
Sample Value: gt2000-01-01
Name:
code
optional
Type:
query
Data Type:
string
Description:
Filters the observations to those that are of the specified code(s). For each specified code, system and code are separated using a URL encoded | character i.e. %7c. Multiple codes can be provided as comma separated values.
Sample Value: http://loinc.org|8302-2
Name:
status
optional
Type:
query
Data Type:
string
Description:
Filters the observations to those having the specified status value(s). Multiple statuses can be specified as comma separated values. Possible values are
- registered
- preliminary
- final
- amended
- corrected
- cancelled
- entered-in-error
- unknown
Sample Value: final,registered
Name:
category
optional
Type:
query
Data Type:
string
Description:
Filters the observations to those that match the specified category. The category value consists of a coding system and a code separated using a URL encoded | character i.e. %7c.
Sample Value: http://terminology.hl7.org/CodeSystem/observation-category|laboratory
Name:
encounter.identifier
optional
Type:
query
Data Type:
string
Description:
Filters the observations to those that match the specified encounter identifier. The identifier consists of identifier namespace, also known as the system, and identifier, separated using a URL encoded | character i.e. %7c.
Sample Value: urn:text:OHCP%7cER20170530.1
Name:
-include-sources
optional
Type:
query
Data Type:
array
Description:
The -include-sources parameter defines which sources should be queried for the results.
Note: Either -include-sources or -exclude-sources parameter can be specified, not both. If -include-sources is specified, ONLY the specified sources will be searched. Note that the sources specified should be enabled.
Sample Value: Orion%20Health%5C%5Cu2122%20R4%20HL7V2%20Encounters
Name:
-exclude-sources
optional
Type:
query
Data Type:
array
Description:
The -exclude-sources parameter defines which sources should NOT be queried for the results.
Note: Either -include-sources or -exclude-sources parameter can be specified, not both. If -exclude-sources is specified, the specified sources will NOT be searched. Note that the sources specified should be enabled..
Sample Value: Orion%20Health%5C%5Cu2122%20R4%20HL7V2%20Encounters
Name:
_format
optional
Type:
query
Data Type:
string
Description:
Media type of the response. It takes precedence over the Accept header.
Possible values are json and xml. The default value is xml.
Sample Value: json
Name:
Accept
optional
Type:
header
Data Type:
string
Description:
Media type of the response.
Possible values are application/json and application/xml. The default value is application/xml.
Sample Value: application/xml
Responses
200
Returns a FHIR Bundle containing 0..* OperationOutcome resources and 0..* Observation resources
400
This response code is returned when the query is invalid e.g. an invalid parameter or a partial token in the search.
Sample Requests
Retrieve all Observations for a Patient identified by a patient identifier
curl -X GET "https://developer-solution/fhir/4.0/Observation/?patient.identifier=ORION%7CAAAA-0124-8" \
-H 'Accept: application/json' \
-H 'Authorization: Basic bGV2ZWwxLnN5c19hOk9yaW9uc3k1IT8='Search for specific Patient Observations
curl -X GET "https://developer-solution/fhir/4.0/Observation/?patient.identifier=ORION%7CAAAA-0124-8&date=gt2000-01-01&code=http://loinc.org%7C8302-2&status=final,registered" \
-H 'Accept: application/json' \
-H 'Authorization: Basic bGV2ZWwxLnN5c19hOk9yaW9uc3k1IT8='Retrieve Observations for a Patient
POST /fhir/4.0/Observation/_search
This method returns all observations for the patient identified by patient.identifier. Optionally filtering by the code, category, date, status and encounter of the observation. This is the secure alternative to the GET search.
Parameters
Name
Type
Data Type
Description
Name:
Content-Type
required
Type:
header
Data Type:
string
Description:
Specifies how to encode the form data. The Content-Type value must be application/x-www-form-urlencoded
Sample Value: application/x-www-form-urlencoded
Name:
patient.identifier
required
Type:
formData
Data Type:
string
Description:
The patient identifier consists of patient identifier namespace, also known as the system, and identifier, separated using a URL encoded | character i.e. %7c.
Sample Value: ORION%7cAAAA-0124-8
Name:
subject.identifier
required
Type:
query
Data Type:
string
Description:
The patient identifier consists of patient identifier namespace, also known as the system, and identifier, separated using a URL encoded | character i.e. %7c.
Note: You must either define the patient.identifier or patient or subject.identifier or subject, not a combination of those parameters.
Sample Value: SYS_A|75849-3478
Name:
patient
required
Type:
query
Data Type:
string
Description:
The patient resource id. Note: You must either define the patient.identifier or patient or subject.identifier or subject, not a combination of those parameters.
Sample Value: IFAUCLJQGAYTIMRNGFAE6USJJ5HA
Name:
subject
required
Type:
query
Data Type:
string
Description:
The patient resource id. Note: You must either define the patient.identifier or patient or subject.identifier or subject, not a combination of those parameters.
Sample Value: G42TQNBZFUZTINZYIBJVSU27IE
Name:
date
optional
Type:
formData
Data Type:
array
Description:
Filters the observations to those with an effectiveDateTime or effectivePeriod on, before, or after a specific date, date-time, or date range.
The supported prefixes are gt, ge, lt, le and eq. If no prefix is used, exact date or date-time matching is implied.
Dates must be formatted according to ISO 8601 either as a date only (e.g. 1997-07-16) or as a date-time including the timezone (e.g. 1997-07-16T19:20:30+13:00).
Ensure that special characters such as + are URL encoded i.e. %2B.
Sample Value: ge2013-01-01T01:00:00%2B13:00
Name:
status
optional
Type:
formData
Data Type:
string
Description:
Filters the observations to those having the specified status value(s). Multiple statuses can be specified as comma separated values. Possible values are
- registered
- preliminary
- final
- amended
- corrected
- cancelled
- entered-in-error
- unknown
Sample Value: final,amended
Name:
code
optional
Type:
formData
Data Type:
string
Description:
Filters the observations to those that are of the specified code(s). For each specified code, both system and the code must be included, separated using a URL encoded | character i.e. %7c. Multiple codes can be provided as comma separated values.
Sample Value: http://loinc.org%7c8480-6,http://loinc.org%7c72166-2
Name:
category
optional
Type:
formData
Data Type:
string
Description:
Filters the observations to those that match the specified category. The category value consists of a coding system and a code separated using a URL encoded | character i.e. %7c.
Sample Value: http://terminology.hl7.org/CodeSystem/observation-category|vital-signs
Name:
encounter.identifier
optional
Type:
formData
Data Type:
string
Description:
Filters the observations to those that match the specified encounter identifier. The identifier consists of identifier namespace, also known as the system, and identifier, separated using a URL encoded | character i.e. %7c.
Sample Value: urn:text:OHCP%7cER20170530.1
Name:
-include-sources
optional
Type:
query
Data Type:
array
Description:
The -include-sources parameter defines which sources should be queried for the results.
Note: Either -include-sources or -exclude-sources parameter can be specified, not both. If -include-sources is specified, ONLY the specified sources will be searched. Note that the sources specified should be enabled.
Sample Value: Orion%20Health%5C%5Cu2122%20R4%20HL7V2%20Encounters
Name:
-exclude-sources
optional
Type:
query
Data Type:
array
Description:
The -exclude-sources parameter defines which sources should NOT be queried for the results.
Note: Either -include-sources or -exclude-sources parameter can be specified, not both. If -exclude-sources is specified, the specified sources will NOT be searched. Note that the sources specified should be enabled..
Sample Value: Orion%20Health%5C%5Cu2122%20R4%20HL7V2%20Encounters
Name:
_format
optional
Type:
query
Data Type:
string
Description:
Media type of the response. It takes precedence over the Accept header.
Possible values are json and xml. The default value is xml.
Sample Value: json
Name:
Accept
optional
Type:
header
Data Type:
string
Description:
Media type of the response.
Possible values are application/json and application/xml. The default value is application/xml.
Sample Value: application/xml
Responses
200
Returns a FHIR Bundle containing 0..* OperationOutcome resources and 0..* Observation resources
400
This response code is returned when the query is invalid e.g. an invalid parameter or a partial token in the search.
Sample Requests
Search for specific Observations identified by subject ID.
curl -X POST "https://developer-solution/fhir/4.0/Observation/_search?subject=G42TQNBZFUZTINZYIBJVSU27IE" \
-H 'Accept: application/json' \
-H 'Authorization: Basic bGV2ZWwxLnN5c19hOk9yaW9uc3k1IT8=' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'category=http://terminology.hl7.org/CodeSystem/observation-category%7Cvital-signs'Retrieve a single Observation
GET /fhir/4.0/Observation/{id}
This method returns the Observation resource matching the requested resource ID.
Parameters
Name
Type
Data Type
Description
Name:
id
required
Type:
path
Data Type:
string
Description:
The id of the Observation resource
Sample Value: shaTWIQUXLR7RLNCR45AMPETZEQYJ6UDN6OV43CD6JCRJJZE3OX6IJQ
Name:
_format
optional
Type:
query
Data Type:
string
Description:
Media type of the response. It takes precedence over the Accept header.
Possible values are json and xml. The default value is xml.
Sample Value: json
Name:
Accept
optional
Type:
header
Data Type:
string
Description:
Media type of the response.
Possible values are application/json and application/xml. The default value is application/xml.
Sample Value: application/xml
Responses
200
Returns an Observation resource matching the requested resource ID.
404
No Observation resource found with the requested resource ID.
Sample Requests
Search for specific Observation identified by resource ID.
curl -X GET "https://developer-solution/fhir/4.0/Observation/shaTWIQUXLR7RLNCR45AMPETZEQYJ6UDN6OV43CD6JCRJJZE3OX6IJQ" \
-H 'Accept: application/json' \
-H 'Authorization: Basic bGV2ZWwxLnN5c19hOk9yaW9uc3k1IT8='Retrieve an Observation's history
GET /fhir/4.0/Observation/{id}/_history
This method returns the change history for an observation resource matching the requested resource ID. Observation resources can be retrieved from multiple data sources, and not all sources are able to return history information. This operation will return an empty set of data if no versions of the specified observation can be found, which includes cases where:
- The specified Observation resource cannot be found.
Parameters
Name
Type
Data Type
Description
Name:
id
required
Type:
path
Data Type:
string
Description:
The id of the Observation resource
Sample Value: shaTZJPZBQMDLCHZG2ZFGLUSU2CUWV2JVI5ZUVHDTNJP6XQCVSJMKFA
Name:
_format
optional
Type:
query
Data Type:
string
Description:
Media type of the response. It takes precedence over the Accept header.
Possible values are json and xml. The default value is xml.
Sample Value: json
Name:
Accept
optional
Type:
header
Data Type:
string
Description:
Media type of the response.
Possible values are application/json and application/xml. The default value is application/xml.
Sample Value: application/xml
Responses
200
A FHIR Bundle containing 0..* Observation resources matching the requested resource ID.
404
- No Observation resource found with the requested resource ID.
- The source providing the Observation resource is not capable of returning history of Observation resources.
Sample Requests
Retrieve history of an observation resource identified by resource ID.
curl -X GET "https://developer-solution/fhir/4.0/Observation/shaTZJPZBQMDLCHZG2ZFGLUSU2CUWV2JVI5ZUVHDTNJP6XQCVSJMKFA/_history" \
-H 'Accept: application/json' \
-H 'Authorization: Basic bGV2ZWwxLnN5c19hOk9yaW9uc3k1IT8='Retrieve a specific version of an Observation resource.
GET /fhir/4.0/Observation/{id}/_history/{versionid}
This method returns the specified version of an observation resource matching the requested resource ID. Observation resources can be retrieved from multiple data sources. This operation will return an empty set of data if no versions of the specified observation can be found, which includes cases where:
- The specified Observation resource cannot be found.
Parameters
Name
Type
Data Type
Description
Name:
id
required
Type:
path
Data Type:
string
Description:
The id of the Observation resource
Sample Value: shaTZJPZBQMDLCHZG2ZFGLUSU2CUWV2JVI5ZUVHDTNJP6XQCVSJMKFA
Name:
versionid
required
Type:
path
Data Type:
string
Description:
The specific version to be retrieved.
Sample Value: 1
Name:
_format
optional
Type:
query
Data Type:
string
Description:
Media type of the response. It takes precedence over the Accept header.
Possible values are json and xml. The default value is xml.
Sample Value: json
Name:
Accept
optional
Type:
header
Data Type:
string
Description:
Media type of the response.
Possible values are application/json and application/xml. The default value is application/xml.
Sample Value: application/xml
Responses
200
Observation with given id was found in given version and it's returned in the response body. The returned resource may be a restricted summary of the full resource due to privacy restrictions, which happens when the Observation resource access level is evaluated to Sealed or Locked. In this case, the Privacy HATEOAS links are present in the response headers. Refer to the Privacy section for details on which fields are included in the restricted summary record.
404
Observation resource id is specified, but no corresponding resource is found. This response can also happen due to the following privacy restrictions:
- Patient is protected by privacy rules and the access level is evaluated to No Access, Sealed or List More.
- Observation is protected by privacy rules and its access level is evaluated to No Access or List More.
Sample Requests
Retrieve a specific version of an observation resource identified by resource ID.
curl -X GET "https://developer-solution/fhir/4.0/Observation/shaTZJPZBQMDLCHZG2ZFGLUSU2CUWV2JVI5ZUVHDTNJP6XQCVSJMKFA/_history/1" \
-H 'Accept: application/json' \
-H 'Authorization: Basic bGV2ZWwxLnN5c19hOk9yaW9uc3k1IT8='