R4 Overview

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.

$ 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/dateTime formats.

Media Types

Cerner supports the R4 FHIR® standard defined media type for JSON content:

application/fhir+json

We encourage you to explicitly request this accept type via the Accept header.

Service Root URL

URLs for the FHIR server vary by the tenant (datasource or client) being accessed, as well as other factors. If the application is a SMART application, the service root url is provided at launch time. For standalone applications, the URL can be requested (or configured) when the application is set up to run against a specific tenant. FHIR calls will be made against URLs of the following format:

:serviceRootURL/:resource[?:parameters]

Open Sandbox

The open sandbox instance allows developers to experiment with the service without requiring authentication. We recommend using this endpoint for initial proof of concepts and integration. The service root URL for this instance is: https://fhir-open.cerner.com/r4/ec2458f2-1e24-41c8-b71b-0e701af7583d/:resource[?:parameters]

Note: The open endpoint exposes read-only resources. No writes are available in sandbox without using authentication.

Secure Sandbox

The secure sandbox instance can be used for testing an application with authorization. The service root URL for this instance is different if the patient or a patient’s proxy is logging in.

Non-Patient: https://fhir-ehr-code.cerner.com/r4/ec2458f2-1e24-41c8-b71b-0e701af7583d/:resource[?:parameters] Patient Access: https://fhir-myrecord.cerner.com/r4/ec2458f2-1e24-41c8-b71b-0e701af7583d/:resource[?:parameters]

Resource

:resource represents the FHIR® standard resource to access. Example: Patient

Parameters

Many API methods take optional parameters. For GET requests, any parameters not specified as a segment in the path can be passed as an HTTP query string parameter:

$ curl -i -H "Accept: application/json+fhir" "https://fhir-open.cerner.com/r4/ec2458f2-1e24-41c8-b71b-0e701af7583d/MedicationOrder?patient=2744010&status=active"

In this example, MedicationOrder is the FHIR® standard resource being accessed, while patient and status are passed in the query string.

Resource Identity

Please note that no ids or identifiers in the Millennium EHR are intended to be used outside of the context of their complete URL. A complete URL is comprised of the service root url, the resource, and the parameters (if any).

For example, one must take into account the entire url and not simply the id or resource + id:

https://fhir-open.cerner.com/r4/ec2458f2-1e24-41c8-b71b-0e701af7583d/Patient/12742400

In another context the id “Patient/12742400” may identify another person entirely. In the following example a different resource may be returned because the context (service root url) has changed.

https://fhir-open.cerner.com/r4/d075cf8b-3261-481d-97e5-ba6c48d3b41f/Patient/12742400

Similarly when considering an identifier one must consider it only in its full context. Even though some identifiers may exist across multiple systems (ex: MRN) it is not guaranteed that they will refer to the same resource.

https://fhir-open.cerner.com/r4/ec2458f2-1e24-41c8-b71b-0e701af7583d/Patient?identifier=urn:oid:1.1.1.1.1.1|10002700

For example, when using the above MRN in a different system, we are not guaranteed that the same Patient resource is returned in the response bundle:

https://fhir-open.cerner.com/r4/d075cf8b-3261-481d-97e5-ba6c48d3b41f/Patient?identifier=urn:oid:1.1.1.1.1.1|10002700

Common Application Errors

Please visit our list of common issues on our FAQ page to be aware of the common issues we’ve identified when validating apps to run on our platform.

Client Errors

There are seven possible types of client errors on API calls that receive request bodies:

  1. Failing to send a required query parameter will result in a 400 Bad Request response.

     HTTP/1.1 400 Bad Request
    
     no supported search parameters provided
    
  2. Requesting the secure endpoint (non-open) without valid credentials will result in a 401 Unauthorized response.

     HTTP/1.1 401 Unauthorized
    
  3. Requesting data from an unknown instance or an instance where the application is not authorized will result in a 403 Forbidden response.

     HTTP/1.1 403 Forbidden
    
     Tenant not valid or accessible
    
  4. Requesting a resource which does not exist will result in a 404 Not Found response.

     HTTP/1.1 404 Not Found
    
  5. Requested a media type other than JSON will result in a 406 Not Acceptable response.

     HTTP/1.1 406 Not Acceptable
    
     Content-Length: 0
    
  6. Performing an update with an out-of-date version id will result in a 409 Conflict Error response.

     HTTP/1.1 409 Conflict Error
    
  7. Performing an add or update with syntactically correct JSON body which is invalid according to business rules will result in a 422 Unprocessable Entity response.

     HTTP/1.1 422 Unprocessable Entity
    

Operation Outcomes

An OperationOutcome may be returned to provide additional context to an error. The tables below describes common OperationOutcomes and their causes.

Retrieve/Search

HTTP Status Cause Severity Code
500 Response is missing a required field fatal required

Create/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

  1. Missing fields required by the HL7 FHIR® specification or any missing status field will result in a 500 Internal Server Error and an OperationOutcome.

     {
       "resourceType": "OperationOutcome",
       "issue": [
         {
           "severity": "fatal",
           "code": "required",
           "location": [
             "/f:AllergyIntolerance/f:status"
           ]
         }
       ]
     }    
    
  2. Missing fields required by HL7 profiles such as Argonaut (DSTU 2) or US Core (STU 3) will result in a DataAbsentReason.

     {
       "coding": [
         {
           "extension": [
             {
               "url": "http://hl7.org/fhir/StructureDefinition/data-absent-reason",
               "valueCode": "unknown"
             }
           ]
         }
       ]
     }
    
  3. Patient consumers requesting a resource with a status of entered-in-error may result in a DataAbsentReason.

     {
       "coding": [
         {
           "extension": [
             {
               "url": "http://hl7.org/fhir/StructureDefinition/data-absent-reason",
               "valueCode": "masked"
             }
           ]
         }
       ]
     }
    
  4. Missing Coding or CodeableConcept fields with a required value set binding will result in 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” will result in either some fields being filtered or returned with a data absent reason with a valueCode of masked. Fields that may contain sensitive information will be 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
GET Used for retrieving resources.
POST Used for creating resources.
PUT Used for updating resources.

HTTP Method Override

If there is no support for HTTP methods such as PUT or PATCH, the request can be made through POST using one of the following:

_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

We have an endpoint secured with OAuth 2.0 with support for SMART Applications. Refer to the extensions on the Conformance.rest.security element in our server metadata.

Scopes supported: launch, profile, fhirUser, openid, online_access, offline_access, patient/Account.read, patient/AllergyIntolerance.read, patient/AllergyIntolerance.write, patient/Appointment.read, patient/Appointment.write, patient/Basic.write, patient/Binary.read, patient/CarePlan.read, patient/CareTeam.read, patient/ChargeItem.read, patient/ChargeItem.write, patient/Communication.read, patient/Communication.write, patient/Condition.read, patient/Condition.write, patient/Consent.read, patient/Coverage.read, patient/Coverage.write, patient/Device.read, patient/DiagnosticReport.read, patient/DocumentReference.read, patient/DocumentReference.write, patient/Encounter.read, patient/Encounter.write, patient/FamilyMemberHistory.read, patient/FamilyMemberHistory.write, patient/Goal.read, patient/Immunization.read, patient/Immunization.write, patient/InsurancePlan.read, patient/MedicationAdministration.read, patient/MedicationRequest.read, patient/MedicationRequest.write, patient utritionOrder.read, patient/Observation.read, patient/Observation.write, patient/Patient.read, patient/Patient.write, patient/Person.read, patient/Procedure.read, patient/Procedure.write, patient/Provenance.read, patient/Provenance.write, patient/Questionnaire.read, patient/QuestionnaireResponse.read, patient/QuestionnaireResponse.write, patient/RelatedPerson.read, patient/RelatedPerson.write, patient/Schedule.read, patient/ServiceRequest.read, patient/Slot.read, patient/Slot.write, system/Account.read, system/AllergyIntolerance.read, system/AllergyIntolerance.write, system/Appointment.read, system/Appointment.write, system/Basic.write, system/Binary.read, system/CarePlan.read, system/CareTeam.read, system/ChargeItem.read, system/ChargeItem.write, system/Communication.read, system/Communication.write, system/Condition.read, system/Condition.write, system/Consent.read, system/Coverage.read, system/Coverage.write, system/Device.read, system/DiagnosticReport.read, system/DocumentReference.read, system/DocumentReference.write, system/Encounter.read, system/Encounter.write, system/FamilyMemberHistory.read, system/FamilyMemberHistory.write, system/FinancialTransaction.write, system/Goal.read, system/Immunization.read, system/Immunization.write, system/InsurancePlan.read, system/Location.read, system/MedicationAdministration.read, system/MedicationRequest.read, system/MedicationRequest.write, system utritionOrder.read, system/Observation.read, system/Observation.write, system/Organization.read, system/Organization.write, system/Patient.read, system/Patient.write, system/Person.read, system/Practitioner.read, system/Practitioner.write, system/Procedure.read, system/Procedure.write, system/Provenance.read, system/Provenance.write, system/Questionnaire.read, system/QuestionnaireResponse.read, system/QuestionnaireResponse.write, system/RelatedPerson.read, system/RelatedPerson.write, system/Schedule.read, system/ServiceRequest.read, system/Slot.read, system/Slot.write, user/Account.read, user/AllergyIntolerance.read, user/AllergyIntolerance.write, user/Appointment.read, user/Appointment.write, user/Basic.write, user/Binary.read, user/CarePlan.read, user/CareTeam.read, user/ChargeItem.read, user/ChargeItem.write, user/Communication.read, user/Communication.write, user/Condition.read, user/Condition.write, user/Consent.read, user/Coverage.read, user/Coverage.write, user/Device.read, user/DiagnosticReport.read, user/DocumentReference.read, user/DocumentReference.write, user/Encounter.read, user/Encounter.write, user/FamilyMemberHistory.read, user/FamilyMemberHistory.write, user/Goal.read, user/Immunization.read, user/Immunization.write, user/InsurancePlan.read, user/Location.read, user/MedicationAdministration.read, user/MedicationRequest.read, user/MedicationRequest.write, user utritionOrder.read, user/Observation.read, user/Observation.write, user/Organization.read, user/Organization.write, user/Patient.read, user/Patient.write, user/Person.read, user/Practitioner.read, user/Practitioner.write, user/Procedure.read, user/Procedure.write, user/Provenance.read, user/Provenance.write, user/Questionnaire.read, user/QuestionnaireResponse.read, user/QuestionnaireResponse.write, user/RelatedPerson.read, user/RelatedPerson.write, user/Schedule.read, user/ServiceRequest.read, user/Slot.read, user/Slot.write

Each resource interaction documents the type of authentication acceptable (patient, provider, and/or system).

Please reference the authorization documentation 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
self Shows the URL of the current page of results.
next Shows the URL of the immediate next page of results.
previous 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 need to take this situation into account 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 thus impacting clinical decision support and patient safety.

Cross Origin Resource Sharing

The API supports Cross Origin Resource Sharing (CORS) for AJAX requests from any origin. You can read the CORS W3C Recommendation, or this intro from the HTML 5 Security Guide.

Here’s a sample 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

This is what a CORS preflight request looks like:

$ 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