R4 Overview
This topic describes the R4 (4.0.1) specification.
Schema
All API access is over HTTPS. See Service Root URL for more information on URL format. All data is sent and received as .JSON format.
$ curl -i -H "Accept: application/fhir+json" https://fhir-open.cerner.com/r4/ec2458f2-1e24-41c8-b71b-0e701af7583d/metadata
HTTP/1.1 200 OK
Date: Tue, 26 Mar 2019 15:50:49 GMT
Cache-Control: no-cache
Vary: Origin
X-Request-Id: ecd13b72-4fde-11e9-8674-8b0a57a130fd
Content-Type: application/json+fhir
{
"resourceType": "CapabilityStatement",
"url": "https://fhir-open.cerner.com/r4/ec2458f2-1e24-41c8-b71b-0e701af7583d/metadata",
"name": "CernerCapabilityStatement",
"title": "Cerner Capability Statement",
"status": "active",
"publisher": "Cerner",
"date": "2019-03-25",
"description": "Cerner implementation of FHIR on top of Millennium",
"kind": "instance",
"implementation": {
"description": "Cerner implementation of FHIR on top of Millennium",
"url": "https://fhir-open.cerner.com/r4/ec2458f2-1e24-41c8-b71b-0e701af7583d"
},
"fhirVersion": "4.0.1",
"format": [
"json"
],
"patchFormat": [
"application/json-patch+json"
],
"rest": [
{
"mode": "server",
"documentation": "Cerner implementation of FHIR on top of Millennium",
"security": {
"cors": true
},
"resource": [
{
"type": "CapabilityStatement",
"interaction": [
{
"code": "read"
}
]
},
{
"type": "Condition",
"interaction": [
{
"code": "read"
},
{
"code": "search-type"
}
],
"searchParam": [
{
"name": "patient",
"definition": "http://hl7.org/fhir/R4/SearchParameter/clinical-patient",
"type": "reference",
"documentation": "Who has the condition. It is a required field if the subject field is not given."
},
{
"name": "subject",
"definition": "http://hl7.org/fhir/R4/SearchParameter/Condition-subject",
"type": "reference",
"documentation": "Who has the condition. It is a required field if the patient field is not given."
},
{
"name": "clinical-status",
"definition": "http://hl7.org/fhir/R4/SearchParameter/Condition-clinical-status",
"type": "token",
"documentation": "The clinical status of the condition."
},
{
"name": "category",
"definition": "http://hl7.org/fhir/R4/SearchParameter/Condition-category",
"type": "token",
"documentation": "The category of the condition. Categories problem-list-item and encounter-diagnosis are supported as of now."
}
]
},
{
"type": "Encounter",
"interaction": [
{
"code": "read"
},
{
"code": "search-type"
}
],
"searchParam": [
{
"name": "_id",
"definition": "http://hl7.org/fhir/R4/SearchParameter/Resource-id",
"type": "token",
"documentation": "A single or comma separated list of Encounter ids. It is a required field if the patient or subject fields are not given."
},
{
"name": "_count",
"definition": "http://hl7.org/fhir/R4/SearchParameter/Resource-count",
"type": "number",
"documentation": "The maximum number of results to return. Not honored when '_id' is set."
},
{
"name": "patient",
"definition": "http://hl7.org/fhir/R4/SearchParameter/clinical-patient",
"type": "reference",
"documentation": "The patient present at the encounter. It is a required field if the _id or subject fields are not given."
},
{
"name": "subject",
"definition": "http://hl7.org/fhir/R4/SearchParameter/Encounter-subject",
"type": "reference",
"documentation": "The patient present at the encounter. It is a required field if the _id or patient fields are not given."
}
]
},
{
"type": "OperationDefinition",
"interaction": [
{
"code": "read"
}
]
},
{
"type": "Patient",
"interaction": [
{
"code": "read"
},
{
"code": "search-type"
}
],
"searchParam": [
{
"name": "_id",
"definition": "http://hl7.org/fhir/R4/SearchParameter/Resource-id",
"type": "token",
"documentation": "A single or comma separated list of Patient ids. Either the '_id' parameter, or a combination of 'identifier', 'birthdate', 'name', 'given', 'family', 'address-postalcode', 'phone', or 'email' parameters must be provided."
},
{
"name": "identifier",
"definition": "http://hl7.org/fhir/R4/SearchParameter/Patient-identifier",
"type": "token",
"documentation": "A patient identifier. Either the '_id' parameter, or a combination of 'identifier', 'birthdate', 'name', 'given', 'family', 'address-postalcode', 'phone', or 'email' parameters must be provided."
},
{
"name": "name",
"definition": "http://hl7.org/fhir/R4/SearchParameter/Patient-name",
"type": "string",
"documentation": "The beginning of any name of the patient. Either the '_id' parameter, or a combination of 'identifier', 'birthdate', 'name', 'given', 'family', 'address-postalcode', 'phone', or 'email' parameters must be provided."
},
{
"name": "given",
"definition": "http://hl7.org/fhir/R4/SearchParameter/individual-given",
"type": "string",
"documentation": "The beginning of the given name of the patient. Either the '_id' parameter, or a combination of 'identifier', 'birthdate', 'name', 'given', 'family', 'address-postalcode', 'phone', or 'email' parameters must be provided."
},
{
"name": "family",
"definition": "http://hl7.org/fhir/R4/SearchParameter/individual-family",
"type": "string",
"documentation": "The beginning of the family name of the patient. Either the '_id' parameter, or a combination of 'identifier', 'birthdate', 'name', 'given', 'family', 'address-postalcode', 'phone', or 'email' parameters must be provided."
},
{
"name": "address-postalcode",
"definition": "http://hl7.org/fhir/R4/SearchParameter/individual-address-postalcode",
"type": "string",
"documentation": "The postal code of the address of the patient. Either the '_id' parameter, or a combination of 'identifier', 'birthdate', 'name', 'given', 'family', 'address-postalcode', 'phone', or 'email' parameters must be provided."
},
{
"name": "birthdate",
"definition": "http://hl7.org/fhir/R4/SearchParameter/individual-birthdate",
"type": "date",
"documentation": "The date of birth of the patient. Either the '_id' parameter, or a combination of 'identifier', 'birthdate', 'name', 'given', 'family', 'address-postalcode', 'phone', or 'email' parameters must be provided."
},
{
"name": "phone",
"definition": "http://hl7.org/fhir/R4/SearchParameter/individual-phone",
"type": "token",
"documentation": "The value of the phone number of the patient. Either the '_id' parameter, or a combination of 'identifier', 'birthdate', 'name', 'given', 'family', 'address-postalcode', 'phone', or 'email' parameters must be provided."
},
{
"name": "email",
"definition": "http://hl7.org/fhir/R4/SearchParameter/individual-email",
"type": "token",
"documentation": "The value of the email address of the patient. Either the '_id' parameter, or a combination of 'identifier', 'birthdate', 'name', 'given', 'family', 'address-postalcode', 'phone', or 'email' parameters must be provided."
},
{
"name": "gender",
"definition": "http://hl7.org/fhir/R4/SearchParameter/individual-gender",
"type": "token",
"documentation": "The administrative gender of the patient. Gender may only be provided if another parameter other than '_id' is provided"
},
{
"name": "_count",
"definition": "http://hl7.org/fhir/R4/SearchParameter/Resource-count",
"type": "number",
"documentation": "The maximum number of results to return. Not honoured when '_id' or 'identifier' are set."
}
]
},
{
"type": "Procedure",
"interaction": [
{
"code": "read"
},
{
"code": "search-type"
}
],
"searchParam": [
{
name: '_id',
definition: 'http://hl7.org/fhir/R4/SearchParameter/Resource-id',
type: 'token',
documentation: 'A single or comma separated list of Procedure ids. It is a required field if the patient or subject fields are not given'
},
{
name: 'patient',
definition: 'http://hl7.org/fhir/R4/SearchParameter/clinical-patient',
type: 'reference',
documentation: 'Search by subject - a patient. It is a required field if the _id or subject fields are not given'
},
{
name: 'subject',
definition: 'http://hl7.org/fhir/R4/SearchParameter/clinical-patient',
type: 'reference',
documentation: 'Search by subject. It is a required field if the _id or patient fields are not given'
}
]
},
{
"type": "StructureDefinition",
"interaction": [
{
"code": "read"
}
]
}
]
}
]
}
Blank fields are omitted.
All timestamps are returned in FHIR standard date or dateTime formats.
Media Types
Oracle Health supports the R4 FHIR standard defined media type for .JSON content:
application/fhir+json
Oracle recommends that you explicitly request this accept type through the
Accept
header.
Common Application Errors
See the FAQs and Common Issues page for more information on common issues identified when validating applications to run on the platform.
Client Errors
The following types of client errors are possible on API calls that receive request bodies:
-
Failing to send a required query parameter returns a
400 (Bad Request)
response.HTTP/1.1 400 Bad Request No supported search parameters provided
-
Requesting the secure endpoint (non-open) without valid credentials returns a
401 (Unauthorized)
response.HTTP/1.1 401 Unauthorized
-
Requesting data from an unknown instance or an instance where the application is not authorized returns a
403 (Forbidden)
response.HTTP/1.1 403 Forbidden Tenant not valid or accessible
-
Requesting a resource that does not exist returns a
404 (Not Found)
response.HTTP/1.1 404 Not Found
-
Requesting a media type other than .JSON returns a
406 (Not Acceptable)
response.HTTP/1.1 406 Not Acceptable Content-Length: 0
-
Performing an update with an out-of-date version returns a
409 (Conflict Error)
response.HTTP/1.1 409 Conflict Error
-
Performing an add or update with a syntactically correct .JSON body that is invalid according to business rules returns a
422 (Unprocessable Entity)
response.HTTP/1.1 422 Unprocessable Entity
Operation Outcomes
An OperationOutcome may be returned to provide additional context for an error. The tables below describe common OperationOutcomes and their causes.
Retrieve or Search
HTTP Status | Cause | Severity | Code |
---|---|---|---|
500 |
Response is missing a required field |
fatal |
required |
Create or Update
HTTP Status | Cause | Severity | Code |
---|---|---|---|
422 |
Body contained unsupported fields |
error |
business-rule |
422 |
Body contained modifier extensions |
error |
extension |
422 |
Body contained implicit rules |
error |
not-supported |
Handling Required Fields
-
Missing fields required by the HL7 FHIR specification or any missing status field return a
500 (Internal Server Error)
and an OperationOutcome.{ "resourceType": "OperationOutcome", "issue": [ { "severity": "fatal", "code": "required", "location": [ "/f:AllergyIntolerance/f:status" ] } ] }
-
Missing fields required by HL7 profiles such as Argonaut (DSTU 2) or US Core (STU 3) return a DataAbsentReason.
{ "coding": [ { "extension": [ { "url": "http://hl7.org/fhir/StructureDefinition/data-absent-reason", "valueCode": "unknown" } ] } ] }
-
Patient consumers requesting a resource with a status of
entered-in-error
may return a DataAbsentReason.{ "coding": [ { "extension": [ { "url": "http://hl7.org/fhir/StructureDefinition/data-absent-reason", "valueCode": "masked" } ] } ] }
-
Missing Coding or CodeableConcept fields with a required value set binding return a DataAbsentReason, though it may return a text component.
{ "coding": [ { "extension": [ { "url": "http://hl7.org/fhir/StructureDefinition/data-absent-reason", "valueCode": "unknown" } ] } ], "text": "Auth (Verified)" }
Filtered Data for Patient or Proxy Access
When accessing data with a patient persona, some data may be filtered as compared to system
or provider access. Resources with a status of entered-in-error
result in some fields being filtered or returned with a data absent reason with a
valueCode
of masked
. Fields that may contain sensitive
information are filtered such as non-instructional notes. For proxy users, regulatory laws
or policies may restrict parental or guardian access to adolescent health records and these
regulations vary from state to state.
General Security Filtering
Not all data can be accessed by all applications or users. Encounter or organization security, privileges, and preference may filter data based on the build in the domain.
HTTP Verbs
Where possible, the FHIR standard strives to use appropriate HTTP verbs for each action.
Verb | Description |
---|---|
|
Used for retrieving resources. |
|
Used for creating resources. |
|
Used for updating resources. |
HTTP Method Override
If HTTP methods such as PUT
or PATCH
are not supported,
you can make a POST
request through one of the following options:
_method parameter
$ curl -i -X POST "https://fhir-ehr-code.cerner.com/r4/ec2458f2-1e24-41c8-b71b-0e701af7583d/Encounter?_method=patch"
X-HTTP-Method-Override header
$ curl -i -X POST -H "X-HTTP-Method-Override: patch" "https://fhir-ehr-code.cerner.com/r4/ec2458f2-1e24-41c8-b71b-0e701af7583d/Encounter"
Note:
When making the override request, appropriate data and headers related to the method you are trying to switch to should be provided.Authorization
An endpoint secured with OAuth 2.0 is available with support for SMART
Applications. See the extensions on the Conformance.rest.security
element in our server metadata.
The scopes below are supported for SMART v1 and SMART v2 applications.
General Scopes
- launch
- profile
- fhirUser
- openid
- online_access
- offline_access
Patient Scopes
- patient/Account.read
- patient/Account.rs
- patient/AllergyIntolerance.crus
- patient/AllergyIntolerance.read
- patient/AllergyIntolerance.write
- patient/Appointment.crus
- patient/Appointment.read
- patient/Appointment.write
- patient/Basic.c
- patient/Basic.write
- patient/Binary.r
- patient/Binary.read
- patient/CarePlan.read
- patient/CarePlan.rs
- patient/CareTeam.read
- patient/CareTeam.rs
- patient/ChargeItem.crs
- patient/ChargeItem.read
- patient/ChargeItem.write
- patient/Communication.crus
- patient/Communication.read
- patient/Communication.write
- patient/Condition.crus
- patient/Condition.read
- patient/Condition.write
- patient/Consent.read
- patient/Consent.rs
- patient/Coverage.cruds
- patient/Coverage.read
- patient/Coverage.write
- patient/Device.read
- patient/Device.rs
- patient/DiagnosticReport.crs
- patient/DiagnosticReport.read
- patient/DocumentReference.crus
- patient/DocumentReference.read
- patient/DocumentReference.write
- patient/Encounter.crus
- patient/Encounter.read
- patient/Encounter.write
- patient/FamilyMemberHistory.crus
- patient/FamilyMemberHistory.read
- patient/FamilyMemberHistory.write
- patient/Goal.read
- patient/Goal.rs
- patient/Immunization.crus
- patient/Immunization.read
- patient/Immunization.write
- patient/InsurancePlan.read
- patient/InsurancePlan.rs
- patient/Media.r
- patient/Media.read
- patient/MedicationAdministration.read
- patient/MedicationAdministration.rs
- patient/MedicationDispense.read
- patient/MedicationDispense.rs
- patient/MedicationRequest.crus
- patient/MedicationRequest.read
- patient/MedicationRequest.write
- patient/NutritionOrder.read
- patient/NutritionOrder.rs
- patient/Observation.crus
- patient/Observation.read
- patient/Observation.write
- patient/Patient.crus
- patient/Patient.read
- patient/Patient.write
- patient/Person.read
- patient/Person.rs
- patient/Procedure.crs
- patient/Procedure.read
- patient/Procedure.write
- patient/Provenance.crs
- patient/Provenance.read
- patient/Provenance.write
- patient/Questionnaire.read
- patient/Questionnaire.rs
- patient/QuestionnaireResponse.read
- patient/QuestionnaireResponse.rus
- patient/QuestionnaireResponse.write
- patient/RelatedPerson.crus
- patient/RelatedPerson.read
- patient/RelatedPerson.write
- patient/Schedule.read
- patient/Schedule.rs
- patient/ServiceRequest.read
- patient/ServiceRequest.rs
- patient/Slot.read
- patient/Slot.rus
- patient/Slot.write
- patient/Specimen.read
- patient/Specimen.rs
System Scopes
- system/Account.read
- system/Account.rs
- system/AllergyIntolerance.crus
- system/AllergyIntolerance.read
- system/AllergyIntolerance.write
- system/Appointment.crus
- system/Appointment.read
- system/Appointment.write
- system/Basic.c
- system/Basic.write
- system/Binary.r
- system/Binary.read
- system/CarePlan.read
- system/CarePlan.rs
- system/CareTeam.read
- system/CareTeam.rs
- system/ChargeItem.crs
- system/ChargeItem.read
- system/ChargeItem.write
- system/Communication.crus
- system/Communication.read
- system/Communication.write
- system/Condition.crus
- system/Condition.read
- system/Condition.write
- system/Consent.read
- system/Consent.rs
- system/Coverage.cruds
- system/Coverage.read
- system/Coverage.write
- system/Device.read
- system/Device.rs
- system/DiagnosticReport.crs
- system/DiagnosticReport.read
- system/DocumentReference.crus
- system/DocumentReference.read
- system/DocumentReference.write
- system/Encounter.crus
- system/Encounter.read
- system/Encounter.write
- system/FamilyMemberHistory.crus
- system/FamilyMemberHistory.read
- system/FamilyMemberHistory.write
- system/FinancialTransaction.c
- system/FinancialTransaction.write
- system/Goal.read
- system/Goal.rs
- system/Immunization.crus
- system/Immunization.read
- system/Immunization.write
- system/InsurancePlan.read
- system/InsurancePlan.rs
- system/Location.read
- system/Location.rs
- system/Media.r
- system/Media.read
- system/MedicationAdministration.read
- system/MedicationAdministration.rs
- system/MedicationDispense.read
- system/MedicationDispense.rs
- system/MedicationRequest.crus
- system/MedicationRequest.read
- system/MedicationRequest.write
- system/NutritionOrder.read
- system/NutritionOrder.rs
- system/Observation.crus
- system/Observation.read
- system/Observation.crs
- system/Observation.write
- system/Organization.read
- system/Organization.write
- system/Patient.crus
- system/Patient.read
- system/Patient.write
- system/Person.read
- system/Person.rs
- system/Practitioner.crs
- system/Practitioner.read
- system/Practitioner.write
- system/Procedure.crs
- system/Procedure.read
- system/Procedure.write
- system/Provenance.crs
- system/Provenance.read
- system/Provenance.write
- system/Questionnaire.read
- system/Questionnaire.rs
- system/QuestionnaireResponse.read
- system/QuestionnaireResponse.rus
- system/QuestionnaireResponse.write
- system/RelatedPerson.crus
- system/RelatedPerson.read
- system/RelatedPerson.write
- system/Schedule.read
- system/Schedule.rs
- system/ServiceRequest.read
- system/ServiceRequest.rs
- system/Slot.read
- system/Slot.rus
- system/Slot.write
- system/Specimen.read
- system/Specimen.rs
User Scopes
- user/Account.read
- user/Account.rs
- user/AllergyIntolerance.crus
- user/AllergyIntolerance.read
- user/AllergyIntolerance.write
- user/Appointment.crus
- user/Appointment.read
- user/Appointment.write
- user/Basic.c
- user/Basic.write
- user/Binary.r
- user/Binary.read
- user/CarePlan.read
- user/CarePlan.rs
- user/CareTeam.read
- user/CareTeam.rs
- user/ChargeItem.crs
- user/ChargeItem.read
- user/ChargeItem.write
- user/Communication.crus
- user/Communication.read
- user/Communication.write
- user/Condition.crus
- user/Condition.read
- user/Condition.write
- user/Consent.read
- user/Consent.rs
- user/Coverage.cruds
- user/Coverage.read
- user/Coverage.write
- user/Device.read
- user/Device.rs
- user/DiagnosticReport.crs
- user/DiagnosticReport.read
- user/DocumentReference.crus
- user/DocumentReference.read
- user/DocumentReference.write
- user/Encounter.crus
- user/Encounter.read
- user/Encounter.write
- user/FamilyMemberHistory.crus
- user/FamilyMemberHistory.read
- user/FamilyMemberHistory.write
- user/Goal.read
- user/Goal.rs
- user/Immunization.crus
- user/Immunization.read
- user/Immunization.write
- user/InsurancePlan.read
- user/InsurancePlan.rs
- user/Location.read
- user/Location.rs
- user/Media.r
- user/Media.read
- user/MedicationAdministration.read
- user/MedicationAdministration.rs
- user/MedicationDispense.read
- user/MedicationDispense.rs
- user/MedicationRequest.crus
- user/MedicationRequest.read
- user/MedicationRequest.write
- user/NutritionOrder.read
- user/NutritionOrder.rs
- user/Observation.crus
- user/Observation.read
- user/Observation.write
- user/Organization.crs
- user/Organization.read
- user/Organization.write
- user/Patient.crus
- user/Patient.read
- user/Patient.write
- user/Person.read
- user/Person.rs
- user/Practitioner.crs
- user/Practitioner.read
- user/Practitioner.write
- user/Procedure.crs
- user/Procedure.read
- user/Procedure.write
- user/Provenance.crs
- user/Provenance.read
- user/Provenance.write
- user/Questionnaire.read
- user/Questionnaire.rs
- user/QuestionnaireResponse.read
- user/QuestionnaireResponse.rus
- user/QuestionnaireResponse.write
- user/RelatedPerson.crus
- user/RelatedPerson.read
- user/RelatedPerson.write
- user/Schedule.read
- user/Schedule.rs
- user/ServiceRequest.read
- user/ServiceRequest.rs
- user/Slot.read
- user/Slot.rus
- user/Slot.write
- user/Specimen.read
- user/Specimen.rs
Each resource interaction documents the type of authentication acceptable (patient, provider, system, or a combination).
See the Authorization Framework page for details on how to authorize with our server.
Pagination
The pagination links are included in the Bundle when a resource returns more items than the Bundle page size. It is important to follow these Link header values instead of constructing your own URLs.
{
"resourceType": "Bundle",
"id": "f22ca456-19a7-45ce-8586-0079495783ef",
"type": "searchset",
"link": [
{
"relation": "self",
"url": "https://fhir-open.cerner.com/r4/ec2458f2-1e24-41c8-b71b-0e701af7583d/Observation?subject%3APatient=12742400&_count=50"
},
{
"relation": "next",
"url": "https://fhir-open.cerner.com/r4/ec2458f2-1e24-41c8-b71b-0e701af7583d/Observation?subject%3APatient=12742400&pageContext=35d95fe0-03bf-426c-bc35-2533f7fde4eb&direction=NEXT"
}
],
...
}
The possible relation
values are:
Name | Description |
---|---|
|
Shows the URL of the current page of results. |
|
Shows the URL of the immediate next page of results. |
|
If paging, shows the URL of the previous page of results. |
Concurrency
Developers need to account for data concurrency within the response. The FHIR specification states:
The results of a search operation are only guaranteed to be current at the moment the operation is executed. After the operation is executed, ongoing actions performed on the resources against which the search was executed will render the results increasingly stale. The significance of this depends on the nature of the search, and the kind of use that is being made of the results.
This is particularly relevant when the server is returning the results in a series of pages. It is at the discretion of the search engine of how to handle ongoing updates to the resources while the search is proceeding.
When results are returned in a series of pages, you may see the same resource ID on subsequent pages. Developers must account for this situation by filtering by resource ID and only return the latest version of that resource ID. Displaying duplicate resource IDs or any other manipulation may misrepresent the data, affecting clinical decision support and patient safety.
Cross Origin Resource Sharing
The API supports Cross Origin Resource Sharing (CORS) for AJAX requests from any origin.
- CORS W3C Recommendation on the Fetch Standard website
- HTML 5 Security Guide on the Google Code Archive
Example GET request sent from the Origin http://example.com
:
$ curl -X GET -i -H "Origin: http://example.com" https://fhir-ehr-code.cerner.com/r4/ec2458f2-1e24-41c8-b71b-0e701af7583d/metadata
HTTP/1.1 200 OK
Access-Control-Allow-Methods: DELETE, GET, POST, PUT, PATCH, OPTIONS, HEAD
Access-Control-Allow-Origin: *
Access-Control-Expose-Headers: ETag, Content-Location, Location, X-Request-Id, WWW-Authenticate, Date
Access-Control-Max-Age: 0
Example CORS preflight request:
$ curl -X OPTIONS -i -H "Origin: http://example.com" -H "Access-Control-Request-Headers: authorization,content-type" -H "Access-Control-Request-Method: GET" https://fhir-ehr-code.cerner.com/r4/ec2458f2-1e24-41c8-b71b-0e701af7583d/metadata
HTTP/1.1 200 OK
Access-Control-Allow-Methods: DELETE, GET, POST, PUT, PATCH, OPTIONS, HEAD
Access-Control-Allow-Origin: *
Access-Control-Expose-Headers: ETag, Content-Location, Location, X-Request-Id, WWW-Authenticate, Date
Access-Control-Max-Age: 0
Access-Control-Allow-Headers: authorization, content-type