Play with FHIR ®

A lightweight REST-based access layer for standard HL7-defined data models. Read the spec

Get FHIR'd up! Epic's Sandbox now supports DSTU2 resources. All resources below are supported in Epic's 2015 release and forward.

New to FHIR? Check out our tutorial to get started!

Patient + Practitioner

The FHIR Patient resource defines demographics, care providers, and other administrative information about a person receiving care at a health organization. The Patient resource can be thought of as the starting point for many different client application workflows; often, a workflow will begin with a patient query and selection, and the server ID will be used to drive additional queries for diagnostic and care-related information.

The FHIR Practitioner resource defines demographics and identifiers for care providers at a health care organization. The Practitioner resource supplements many of the resources within FHIR by providing information about a primary care provider, prescriber, or the clinician in volved in ordering a diagnostic test for a patient.

To play in an interactive sandbox, navigate to this page
using Chrome, Safari, or Firefox ("FHIRFox"??).
 Click the button. Go on.
See more

Endpoints

Patient Search Interaction

Relative URL FHIR Interaction HTTP Method Action
/Patient?[parameter={value}] Search Get Retrieve Patient resources meeting the specified search criteria

The search interaction enables the client to query for patients based on a specified set of demographics information. The Patient Search endpoint allows clients to establish an identifier for a patient without previously receiving unique identification from the server for the patient. Epic's sandbox currently supports the following query parameters for patient demographic queries:

Note: Epic's patient search implementation only returns patients with strong demographics matches. Most query parameters will return no results unless used in concert with more specific demographic information. Consult the Examples section below for suggestion on combining query parameters.
Note: Epic's support of the Patient resource only allows retrieving the most up-to-date demographics info. Previous demographic information cannot be queried for.


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 Search for Patient resources using a last name or family name.  This parameter is used to find patients with matching family 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 given 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.
Examples
Query Result
/Patient?family=Argonaut&given=Jason Returns 1 Argonaut patient (Jason)
/Patient?identifier=E3814&gender=female Returns 1 Williams patient (Emily)

Other patients available in our sandbox include:

  • Jessica Argonaut
  • Flapjacks Ragsdale
  • Pancakes Ragsdale
  • Waffles Ragsdale
  • Bacon Ragsdale
  • Emily Williams (three of them!)
  • James Kirk

Patient Read Interaction

Relative URL FHIR Interaction HTTP Method Action
/Patient/{ID} Read Get Retrieve patient by ID

The read interaction enables the look up of a Patient resource by a constant server ID. The read interaction allows clients to store only the server ID, and with a single request, retrieve the most up-to-date demographics on a patient. Read interactions typically begin with a client having previously established a relationship, often through querying for patients through the search interaction.

Supported Patient Extensions

In addition to the Standard FHIR Patientresource, Epic supports the following patient-level extensions:

Extension Name Description Example
US Core Race Coded value of the Patient's documented race using the HL7 Version 3 Race Code System.
					
{
    "url": "http://hl7.org/fhir/StructureDefinition/us-core-race",
    "valueCodeableConcept": {
    "text": "Asian",
    "coding": [
        {
        "system": "2.16.840.1.113883.5.104",
        "code": "2028-9",
        "display": "Asian"
        }
    ]
    }
}
			         
				
US Core Ethnicity Coded value of the Patient's documented ethnicity using the HL7 Version 3 Ethnicity Code System.
					
{
    "url": "http://hl7.org/fhir/StructureDefinition/us-core-ethnicity",
    "valueCodeableConcept": {
    "text": "Not Hispanic or Latino",
    "coding": [
        {
        "system": "2.16.840.1.113883.5.50",
        "code": "2186-5",
        "display": "Not Hispanic or Latino"
        }
    ]
    }
}	
			         
				
US Core Birth Sex Coded value of the Patient's documented birth sex using the HL7 Version 3 Administrative Gender Code System, as required by ONC regulation. Note: if no birth sex is documented, a value will not be returned.
					
{
    "url": "http://hl7.org/fhir/StructureDefinition/us-core-birth-sex",
    "valueCodeableConcept": {
    "text": "Male",
    "coding": [
        {
        "system": "http://hl7.org/fhir/v3/AdministrativeGender",
        "code": "M",
        "display": "Male"
        }
    ]
    }
}
					
				

Patient Create Interaction

The create request sends a Patient resource through the request body to the server. For more technical details on our implementation of this resource, check out our App Orchard program.

Practitioner Read Interaction

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

The read interaction enables the look up of a Practitioner resource by a constant server ID. The read interaction allows clients to store only the server ID, and with a single request, retrieve the most up-to-date demographics on a practitioner. Read interactions typically begin with a client having previously established a relationship, often through receiving the provider reference as a part of the Patient resource.

Errors

When things go wrong, the Epic EMR responds with an error code and a human-readable description to describe the incorrect submission. Currently, the error code is not included in the REST version of the specification, but it is provided here for your reference. These codes are meant for developer use only - they should not be presented to end users. Instead, your application should interpret the codes and provide user-friendly resolution steps when data cannot be filed.

FHIR Errors come in two flavors:

  • Fatal Errors cause the response to contain no results and are usually due to requests from the client processed as invalid - missing or invalid data in the request, unauthorized access, or expired content in the system.
  • Warning Errors accompany a successful response and are used to indicate that part of a request could not be fulfilled - for example, if a status is unknown, but the request can be fulfilled, the API will return the data and indicate that part of the request couldn't be understood.

FHIR Error Codes

Error Code Severity Description Example
4100 Fatal The resource request contained an invalid parameter Invalid parameter such as a non existent patient ID: AllergyIntolerance?patient=foo
4101 Warning Resource request returns no results A request for data that was otherwise valid but no information was documented or found (i.e. a patient with no pertinent implanted devices, or a demographic search where no patients met the search criteria).
4102 Fatal The read resource request contained an invalid ID Invalid Resource ID: AllergyIntolerance/foo
4107 Fatal The read resource request has been merged Requesting a Patient which has been merged - in this event, in addition to the error response, we will respond with an HTTP Redirect status. To browsers and many HTTP clients, the redirect will be transparent.
4110 Fatal No parameters are provided in the search request An invalid search request such as : AllergyIntolerance?
4111 Fatal Required search parameter missing from request A request missing a required parameter (such as the patient): Condition?category=diagnosis
4112 Fatal The resource request contained an invalid combination of parameters A search containing multiple different patient ID: AllergyIntolerance?patient=[ID 1]&patient=[ID 2]
4113 Fatal Session ID for cached search results has expired. Making a request for previously accessed paginated search results after the search has expired.
4115 Fatal Required search parameter has an invalid value An invalid parameter required for searching: Condition?Patient=[ID]&category=foo
4117 Warning No CVX code for Immunization resource Request for an Immunization resource without a documented CVX code.
4118 Fatal User not authorized for request Request data that the authenticated user is not allowed access to view (i.e. a patient asking for data about a stranger's allergies).
4119 Warning Additional data may be present for patient Request data while authenticated as an authorized patient or patient proxy. Inidicates that data available to the patient may not be the complete medical record within the system.