Overview

This describes the resources that make up Cerner’s implementation of the HL7® FHIR® standard. If you have any problems or requests, please post to our developer group.

Current Version

Cerner’s implementation currently supports the DSTU 2 Final (1.0.2) version of the FHIR® standard.

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/json+fhir" https://fhir-open.sandboxcerner.com/dstu2/0b8a0111-e8e6-4c26-a91c-5069cbc6b1ca/metadata
HTTP/1.1 200 OK
Date: Tue, 05 Jan 2016 20:02:23 GMT
cache-control: no-cache
vary: Origin,User-Agent
strict-transport-security: max-age=631152000
server-response-time: 6003.4422970000005
x-xss-protection: 1; mode=block
x-request-id: 637dd651-6943-4d45-8e8a-0577da7640a2
x-runtime: 6.003411
x-frame-options: SAMEORIGIN
x-content-type-options: nosniff
Status: 200 OK
Content-Type: application/json+fhir; charset=utf-8
Transfer-Encoding: chunked

{
  "resourceType": "Conformance",
  "text": {
    "status": "generated",
    "div": "<div>Generated Conformance Statement</div>"
  },
  "url": "https://fhir-open.sandboxcerner.com/dstu2/0b8a0111-e8e6-4c26-a91c-5069cbc6b1ca/metadata",
  "name": "Cerner Conformance Statement",
  "status": "draft",
  "publisher": "Cerner",
  "date": "2015-12-03T00:00:00+00:00",
  "description": "Describes capabilities of this server",
  "kind": "instance",
  "fhirVersion": "1.0.2",
  "acceptUnknown": "no",
  "format": [
    "json"
  ],
  "rest": [
    {
      "mode": "server",
      "documentation": "All the functionality defined in FHIR",
      "security": {
        "cors": true
      },
      "resource": [
        {
          "type": "AllergyIntolerance",
          "interaction": [
            {
              "code": "read"
            },
            {
              "code": "search-type"
            }
          ],
          "searchParam": [
            {
              "name": "_id",
              "type": "token",
              "documentation": "A single or comma separated list of AllergyIntolerance ids. It is a required field if patient field is not given"
            },
            {
              "name": "patient",
              "type": "reference",
              "documentation": "Who the sensitivity is for. It is a required field if _id field is not given"
            },
            {
              "name": "status",
              "type": "token",
              "documentation": "Certainty of the allergy or intolerance"
            }
          ]
        },
        {
          "type": "Condition",
          "interaction": [
            {
              "code": "read"
            },
            {
              "code": "search-type"
            }
          ],
          "searchParam": [
            {
              "name": "_id",
              "type": "token",
              "documentation": "A single or comma separated list of Condition ids. It is a required field if patient field is not given"
            },
            {
              "name": "patient",
              "type": "reference",
              "documentation": "The patient who has the condition. It is a required field if _id field is not given"
            },
            {
              "name": "clinicalstatus",
              "type": "token",
              "documentation": "A list of desired clinical statuses of the condition"
            },
            {
              "name": "category",
              "type": "token",
              "documentation": "The category of the condition"
            }
          ]
        },
        {
          "type": "Device",
          "interaction": [
            {
              "code": "read"
            },
            {
              "code": "search-type"
            }
          ],
          "searchParam": [
            {
              "name": "patient",
              "type": "reference",
              "documentation": "The patient who has the device affixed. It is a required field if _id field is not given"
            },
            {
              "name": "_id",
              "type": "token",
              "documentation": "A single or comma separated list of Device ids. It is a required field if patient field is not given"
            }
          ]
        },
        {
          "type": "DocumentReference",
          "interaction": [
            {
              "code": "search-type"
            }
          ],
          "searchParam": [
            {
              "name": "patient",
              "type": "reference",
              "documentation": "The patient the document is about"
            },
            {
              "name": "type",
              "type": "token",
              "documentation": "The type of the document"
            }
          ]
        },
        {
          "type": "MedicationOrder",
          "interaction": [
            {
              "code": "search-type"
            }
          ],
          "searchParam": [
            {
              "name": "patient",
              "type": "reference",
              "documentation": "The identity of a patient to list dispenses for. It is a required field"
            },
            {
              "name": "status",
              "type": "token",
              "documentation": "The status of the med, may be a list separated by commas. (Active and draft statuses must be queried separately from completed, on-hold, and stopped statuses. The superseded and entered-in-error statuses are not supported). It is a required field"
            },
            {
              "name": "timing-boundsperiod-end",
              "type": "date",
              "documentation": "The stop time of the order. Must be prefixed by 'le' (currently only support querying for orders completed prior to a certain time). Not accepted when querying active or draft orders"
            },
            {
              "name": "_count",
              "type": "number",
              "documentation": "The number of items to include in a page. Currently ignored if querying for active or draft statuses"
            }
          ]
        },
        {
          "type": "MedicationStatement",
          "interaction": [
            {
              "code": "search-type"
            }
          ],
          "searchParam": [
            {
              "name": "patient",
              "type": "reference",
              "documentation": "The identity of a patient to list statements for. It is a required field."
            },
            {
              "name": "status",
              "type": "token",
              "documentation": "One or more medication statement status values separated by commas."
            },
            {
              "name": "effectivedate",
              "type": "date",
              "documentation": "The date-time which should fall within the period the patient was taking (or not taking) the medication. Must be prefixed by 'ge'."
            },
            {
              "name": "_count",
              "type": "number",
              "documentation": "The maximum number of results to include in a page."
            }
          ]
        },
        {
          "type": "Patient",
          "interaction": [
            {
              "code": "read"
            },
            {
              "code": "search-type"
            }
          ],
          "searchParam": [
            {
              "name": "_id",
              "type": "token",
              "documentation": "The logical resource id associated with the resource (must be supported by all servers). It is a required field if no birthdate, identifier, name or telecom field is given"
            },
            {
              "name": "birthdate",
              "type": "date",
              "documentation": "The patient's date of birth. It is a required field if no _id, identifier, name or telecom field is given"
            },
            {
              "name": "identifier",
              "type": "token",
              "documentation": "A patient identifier. It is a requried field if no _id, birthdate, name or telecom field is given"
            },
            {
              "name": "name",
              "type": "string",
              "documentation": "A portion of either family or given name of the patient. It is a required field if no _id, birthday, identifier or telecom field is given"
            },
            {
              "name": "telecom",
              "type": "string",
              "documentation": "The value in any kind of telecom details of the patient. It is a required field if no _id, birthdate, identifier or name is given"
            },
            {
              "name": "_count",
              "type": "number",
              "documentation": "The maximum number of results to return"
            }
          ]
        }
      ]
    }
  ]
}

Blank fields are omitted.

All timestamps are returned in FHIR® standard date/dateTime formats.

Media Types

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

application/json+fhir
application/json

We encourage you to explicitly request one of these types 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.sandboxcerner.com/dstu2/0b8a0111-e8e6-4c26-a91c-5069cbc6b1ca/: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.sandboxcerner.com/dstu2/0b8a0111-e8e6-4c26-a91c-5069cbc6b1ca/:resource[?:parameters] Patient Access: https://fhir-myrecord.sandboxcerner.com/dstu2/0b8a0111-e8e6-4c26-a91c-5069cbc6b1ca/: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.sandboxcerner.com/dstu2/0b8a0111-e8e6-4c26-a91c-5069cbc6b1ca/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.sandboxcerner.com/dstu2/0b8a0111-e8e6-4c26-a91c-5069cbc6b1ca/Patient/1316024

In another context the id “Patient/1316024” 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.sandboxcerner.com/dstu2/d075cf8b-3261-481d-97e5-ba6c48d3b41f/Patient/1316024

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.sandboxcerner.com/dstu2/0b8a0111-e8e6-4c26-a91c-5069cbc6b1ca/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.sandboxcerner.com/dstu2/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 identify 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 resule 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
    

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.

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.

Each resource interaction documents the type of authentication acceptable (patient, provider, and/or system). While an interaction may list system authentication, this is currently available only in sandbox for beta testing and is not available in production yet.

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 multiple items. 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.sandboxcerner.com/dstu2/0b8a0111-e8e6-4c26-a91c-5069cbc6b1ca/Observation?subject%3APatient=1316024&_count=50"
  }, {
    "relation": "next",
    "url": "https://fhir-open.sandboxcerner.com/dstu2/0b8a0111-e8e6-4c26-a91c-5069cbc6b1ca/Observation?subject%3APatient=1316024&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.

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 request sent from the origin http://example.com:

$ curl -i -H "Origin: http://example.com" -H "Accept: application/json+fhir" https://fhir-open.sandboxcerner.com/dstu2/0b8a0111-e8e6-4c26-a91c-5069cbc6b1ca/metadata
HTTP/1.1 200 OK
Access-Control-Allow-Origin: http://example.com
Access-Control-Allow-Methods: DELETE, GET, POST, PUT, OPTIONS, HEAD
Access-Control-Max-Age: 0
Access-Control-Allow-Credentials: true

This is what a CORS preflight request looks like:

$ curl -X OPTIONS -i -H "Origin: http://example.com" https://fhir-open.sandboxcerner.com/dstu2/0b8a0111-e8e6-4c26-a91c-5069cbc6b1ca/metadata
HTTP/1.1 204 No Content
Access-Control-Allow-Origin: http://example.com
Access-Control-Allow-Methods: DELETE, GET, POST, PUT, OPTIONS, HEAD
Access-Control-Max-Age: 0
Access-Control-Allow-Credentials: true