US Core Implementation Guide (Release 1.1.0 Ballot )

This page is part of the US Core (v1.1.0: STU2 Ballot 1) based on FHIR R3. The current version which supercedes this version is 5.0.1. For a full list of available versions, see the Directory of published versions

CapabilityStatement: server

Formats: XML, JSON, Turtle

  • FHIR Version: 3.0.1
  • Supported formats: xml, json
  • Published: 2017-12-22
  • Published by: Health Level Seven International US Realm Steering Committee

The Section describes the expected capabilities of the US Core Server actor which is responsible for providing responses to the queries submitted by the US Core Requestors. The complete list of FHIR profiles, RESTful operations, and search parameters supported by US Core Servers are defined. Systems implementing this capability statement should meet the ONC 2015 Common Clinical Data Set (CCDS) access requirement for Patient Selection 170.315(g)(7) and Application Access - Data Category Request 170.315(g)(8). US Core Clients have the option of choosing from this list to access necessary data based on their local use cases and other contextual requirements.

Behavior

Description:

The US Core Server SHALL:

  1. Support the US Core Patient resource profile.
  2. Support at least one additional resource profile from the list of US Core Profiles.
  3. Implement the RESTful behavior according to the FHIR specification.
  4. Return the following response classes:
    • (Status 200): successful operation
    • (Status 400): invalid parameter
    • (Status 401/4xx): unauthorized request
    • (Status 403): insufficient scope
    • (Status 404): unknown resource
    • (Status 410): deleted resource.
  5. Support json resource formats for all US Core interactions.
  6. Declare a CapabilityStatement identifying the list of profiles, operations, search parameter supported.

The US Core Server SHOULD:

  1. Support xml resource formats for all US Core interactions.
  2. Identify the US Core profiles supported as part of the FHIR meta.profile attribute for each instance.

Security:

US Core Servers SHALL:

  1. Implement the security requirements documented in the this IG.
  2. A server has ensured that every API request includes a valid Authorization token, supplied via: Authorization: Bearer {server-specific-token-here}
  3. A server has rejected any unauthorized requests by returning an HTTP 401 Unauthorized response code.

Profile Interaction Summary:

  1. All servers SHALL make available the read and search interactions for the Profiles the server chooses to support.
  2. All servers SHOULD make available the vread and history-instance interactions for the Profiles the server chooses to support.

Summary of US Core search criteria

Specific server search capabilities are described in detail in each of the resource sections below.

Resource Type Supported Profiles Supported Searches Supported Includes
Patient US Core Patient Profile name , family , given , identifier , gender , birthdate , name + gender , name + birthdate , family + gender , given + gender
AllergyIntolerance US Core AllergyIntolerance Profile patient
CarePlan US Core CarePlan Profile patient , category , status , date, patient + category , patient + category + date , patient + category + status , patient + category + status + date
CareTeam US Core CareTeam Profile patient , status, patient + status
Condition US Core Condition Profile patient , category , clinicalstatus, patient + clinicalstatus , patient + category
Device US Core Device Profile patient
DiagnosticReport US Core DiagnosticReport Profile patient , category , code , date, patient + category , patient + category + date , patient + category + code, patient + category + code + date
DocumentReference US Core DocumentReference Profile patient , patient + period + type , patient + date + $docref
Encounter US Core Encounter Profile patient , patient + date
Goal US Core Goal Profile patient , date, patient + date
Immunization US Core Immunization Profile patient
Location US Core Location Profile name , address
Medication US Core Medication Profile
MedicationStatement US Core MedicationStatement Profile patient MedicationStatement.medication
MedicationRequest US Core MedicationRequest Profile patient MedicationRequest.medication
Observation US Core Result Observation Profile, Vital Signs Profile, US Core Smoking Status Observation Profile patient , category , code , date, patient + category , patient + category + date , patient + category + code, patient + category + code + date
Organization US Core Organization Profile identifier , name , address
Practitioner US Core Practitioner Profile identifier , name
PractitionerRole US Core PractitionerRole Profile identifier , family + given, specialty
Procedure US Core Procedure Profile patient , date , patient + date

Resource Details:

Patient

Supported Profiles: US Core Patient Profile

Search Criteria:

  1. A server SHALL be capable of returning a patient using:

    GET [base]/Patient/[id].

  2. A server SHALL be capable of returning a patient by identifier using

    GET [base]/Patient?identifier=[system]|[code]

  3. A server SHALL be capbable of returning a patient by supporting at a minimum the following search parameters when at least 2 are present:

    • name
    • gender

    • birthdate

      • for example:

        GET [base]/Patient?name=[name]&gender=[gender]

Search Parameters:

Conformance Parameter Type
SHALL name string
SHALL identifier token
SHALL family +gender string + token
SHALL given +gender string + token
SHALL name+gender string + token
SHALL name+birthdate string + date

AllergyIntolerance

Supported Profiles: US Core AllergyIntolerance Profile

Search Criteria:

  1. A server SHALL be capable of returning all patient’s allergies using:

    GET [base]/AllergyIntolerance?patient=[id]

Search Parameters:

Conformance Parameter Type
SHALL patient reference

CarePlan

Supported Profiles: US Core CarePlan Profile

Search Criteria:

  1. A server SHALL be capable of returning all of a patient’s Assessment and Plan of Treatment information using:

    GET [base]/CarePlan?patient=[id]&category=assess-plan

  2. A server SHALL be capable of returning a patient’s Assessment and Plan of Treatment information over a specified time period using:

    GET [base]/CarePlan?patient=[id]&category=assess-plan&date=[date]

  3. A server SHOULD be capable returning all of a patient’s active Assessment and Plan of Treatment information using

    GET [base]/CarePlan?patient=[id]&category=assess-plan&status=active

  4. A server SHOULD be capable returning a patient’s active Assessment and Plan of Treatment information over a specified time period using

    GET [base]/CarePlan?patient=[id]&category=assess-plan&status=active&date=[date]

Search Parameters:

Conformance Parameter Type Modifiers
SHALL patient + category reference + token
SHALL patient + category + date reference + token + date date modifiers‘ge’,‘le’,’gt’,’lt’
SHOULD patient + category + status reference + token
SHOULD patient + category + date + status reference + token + date date modifiers‘ge’,‘le’,’gt’,’lt’

CareTeam

Supported Profiles: US Core CareTeam Profile

Search Criteria:

  1. A server SHALL be capable of returning a patient’s current care team members using:

    GET [base]/CareTeam?patient=[id]&status=active

Search Parameters:

Conformance Parameter Type
SHALL patient + status reference + token

Condition

Supported Profiles: US Core Condition Profile

Search Criteria:

  1. A server SHALL be capable of returning all problems and health concerns for a patient, including current as well as historical problems and health concerns using:

    GET [base]/Condition?patient=[id]

  2. A server SHOULD be capable returning all of a patient’s active problems and health concerns using:

    GET [base]/Condition?patient=[id]&clinicalstatus=active,recurrance,remission

  3. A server SHOULD be capable returning all of a patient’s problems or all of patient’s health concerns using:

    GET [base]/Condition?patient=[id]&category=[problem|health-concern]

Search Parameters:

Conformance Parameter Type
SHALL patient reference
SHOULD patient + category reference + token
SHOULD patient + clinicalstatus reference + token

Device

Supported Profiles: US Core Device Profile

Search Criteria:

  1. A server SHALL be capable of returning all Unique device identifier(s)(UDI) for a patient’s implanted device(s):

    GET [base]/Device?patient=[id]

Search Parameters:

Conformance Parameter Type
SHALL patient reference

DiagnosticReport

Supported Profiles: US Core DiagnosticReport Profile

Search Criteria:

  1. A server SHALL be capable of returning all of a patient’s laboratory diagnostic reports queried by category using:

    GET [base]/DiagnosticReport?patient=[id]&category=LAB

  2. A server SHALL be capable of returning all of a patient’s laboratory diagnostic reports queried by category code and date range using:

    GET [base]/DiagnosticReport?patient=[id]&category=LAB&date=[date]{&date=[date]}

  3. A server SHALL be capable of returning all of a patient’s laboratory diagnostic reports queried by category and code using:

    GET [base]/DiagnosticReport?patient=[id]&category=LAB&code=[LOINC]

  4. A server SHOULD be capable of returning all of a patient’s laboratory diagnostic reports queried by category and one or more codes and date range using:

    GET [base]/DiagnosticReport?patient=[id]&category=LAB&code=[LOINC1{,LOINC2,LOINC3,…}]&date=[date]{&date=[date]}

Search Parameters:

Conformance Parameter Type Modifiers
SHALL patient + category reference + token
SHALL patient + category + code reference + token
SHALL patient + category + date reference + token + date date modifiers‘ge’,‘le’,’gt’,’lt’
SHOULD patient + category + code + date reference + token + date date modifiers‘ge’,‘le’,’gt’,’lt’

DocumentReference

Supported Profiles: US Core DocumentReference Profile

Search Criteria:

  1. A server SHALL be capable of returning all of a patient’s DocumentReferences using:

    GET [base]/DocumentReference?patient=[id]

  2. A server SHALL be capable of responding to a $docref operation. At minimum, it must return a reference to a CCD document.

    GET [base]/DocumentReference/$docref?patient=[id]

  3. A server SHOULD be capable of returning all of all of a patient’s DocumentReferences for a given time period and document type:

    GET [base]/DocumentReference?patient=[id]&type=[type]&period=[date]{&date=[date]}

Search Parameters:

Conformance Parameter Type Modifiers
SHALL patient reference
SHALL patient + $docref reference + oepration
SHOULD patient + type + period reference + token + date date modifiers‘ge’,‘le’,’gt’,’lt’

Encounter

Supported Profiles: US Core Encounter Profile

Search Criteria:

  1. A server SHALL be capable of returning all of a patient’s encounters using:

    GET [base]/Encounter?patient=[id]

  2. A server SHALL be capable of returning all of all of a patient’s encounters over a specified time period using:

    GET [base]/Encounter?patient=[id]&date=[date]{&date=[date]}

Search Parameters:

Conformance Parameter Type Modifiers
SHALL patient reference
SHALL patient + date reference + date date modifiers‘ge’,‘le’,’gt’,’lt’

Goal

Supported Profiles: US Core Goal Profile

Search Criteria:

  1. A server SHALL be capable of returning all of a patient’s goals using:

    GET [base]/Goal?patient=[id]

  2. A server SHALL be capable of returning all of all of a patient’s goals over a specified time period using:

    GET [base]/Goal?patient=[id]&date=[date]{&date=[date]}

Search Parameters:

Conformance Parameter Type Modifiers
SHALL patient reference
SHALL patient + date reference + date date modifiers‘ge’,‘le’,’gt’,’lt’

Immunization

Supported Profiles: US Core Immunization Profile

Search Criteria:

  1. A server SHALL be capable of returning all immunizations for a patient using:

    GET [base]/Immunization?patient=[id]

Search Parameters:

Conformance Parameter Type
SHALL patient reference

Location

Supported Profiles: US Core Location Profile

Search Criteria:

  1. A server SHALL be capable of returning a location by name using:

    GET [base]/Location?name=[string]

  2. A server SHALL be capable of returning a location by address using:

    GET [base]/Location?address=[string]

Search Parameters:

Conformance Parameter Type
SHALL name string
SHALL address string

Medication

Supported Profiles: US Core Medication Profile

The MedicationStatement and MedicationRequest resources can represent a medication, using an external reference to a Medication resource. If an external Medication Resource is used in a MedicationStatement or a MedicationRequest, then the READ and SEARCH Criteria SHALL be supported.

MedicationStatement

Supported Profiles: US Core MedicationStatement Profile

Search Criteria:

The MedicationStatement resources can represent a medication using either a code or refer to the Medication resource. When referencing a Medication resource, the resource may be contained or an external resource. The server application MAY choose any one way or more than one method, but if an external reference to Medication is used, the server SHALL support the _include parameter for searching this element. The client application must support all methods.

A server SHALL be capable of returning all medications for a patient using one of or both:

GET /MedicationStatement?patient=[id]

GET /MedicationStatement?patient=[id]&_include=MedicationStatement:medication

Search Parameters:

Conformance Parameter Type _include(see documentation)
SHALL patient reference MedicationStatement:medication

MedicationRequest

Supported Profiles: US Core MedicationRequest Profile

Search Criteria:

The MedicationRequest resources can represent a medication using either a code or refer to the Medication resource. When referencing a Medication resource, the resource may be contained or an external resource. The server application MAY choose any one way or more than one method, but if an external reference to Medication is used, the server SHALL support the _include parameter for searching this element. The client application must support all methods.

A server SHALL be capable of returning all medications for a patient using one of or both:

GET /MedicationRequest?patient=[id]

GET /MedicationRequest?patient=[id]&_include=MedicationRequest:medication

Search Parameters:

Conformance Parameter Type _include(see documentation)
SHALL patient reference MedicationRequest:medication

Observation

Supported Profiles:

  1. US Core Result Observation Profile

    Search Criteria:

    1. A server SHALL be capable of returning all of a patient’s laboratory results queried by category using:

      GET [base]/Observation?patient=[id]&category=laboratory

    2. A server SHALL be capable of returning all of a patient’s laboratory results queried by category code and date range using:

      GET [base]/Observation?patient=[id]&category=laboratory&date=[date]{&date=[date]}

    3. A server SHALL be capable of returning all of a patient’s laboratory results queried by category and code using:

      GET [base]/Observation?patient=[id]&category=laboratory&code=[LOINC]

    4. A server SHOULD be capable of returning all of a patient’s laboratory results queried by category and one or more codes and date range using:

      GET [base]/Observation?patient=[id]&category=laboratory&code=[LOINC1{,LOINC2,LOINC3,...}]&date=[date]{&date=[date]}

  2. Vital Signs Profile

    Search Criteria:

    1. A server SHALL be capable of returning all of a patient’s vital signs that it supports using:

      GET [base]/Observation?patient=[id]&category=vital-signs

    2. A server SHALL be capable of returning all of a patient’s vital signs queried by date range using:

      GET [base]/Observation?patient=[id]&category=vital-signs&date=[date]{&date=[date]}

    3. A server SHALL be capable of returning any of a patient’s vital signs queried by one or more of the codes listed below using:

      GET [base]/Observation?patient=[id]&code[vital sign LOINC{,LOINC2,LOINC3,…}]

    4. A server SHOULD be capable of returning any of a patient’s vital signs queried by one or more of the codes listed below and date range using:

      GET [base]/Observation?patient=[id]&code=[LOINC{,LOINC2…}]vital-signs&date=[date]{&date=[date]}

  3. US Core Smoking Status Observation Profile

    Search Criteria:

    1. A server SHALL be capable of returning a patient’s smoking status using:

      GET [base]/Observation?patient=[id]&code=72166-2

Search Parameters:

Conformance Parameter Type Modifiers
SHALL patient + category reference + token
SHALL patient + category + code reference + token
SHALL patient + category + date reference + token + date date modifiers‘ge’,‘le’,’gt’,’lt’
SHOULD patient + category + code + date reference + token + date date modifiers‘ge’,‘le’,’gt’,’lt’

Organization

Supported Profiles: US Core Organization Profile

Search Criteria:

  1. A server SHALL be capable of returning an organization by identifier using:

    `GET [base]/Organization?identifier=[system] [code]’

  2. A server SHALL be capable of returning an organization by name using:

    GET [base]/Organization?name=[string]

  3. A server SHALL be capable of returning an organization by address using:

    GET [base]/Organization?address=[string]

Search Parameters:

Conformance Parameter Type
SHALL identifier token
SHALL name string
SHALL address string

Practitioner

Supported Profiles: US Core Practitioner Profile

Search Criteria:

  1. A server SHALL be capable of returning a practitioner by identifier using:

    GET [base]/Practitioner?identifier=[system]|[code]

  2. A server SHALL be capable of returning a practitioner by name using:

    GET [base]/Practitioner?family=[string]&given=[string]

Search Parameters:

Conformance Parameter Type
SHALL identifier token
SHALL name string

PractitionerRole

Supported Profiles: US Core PractitionerRole Profile

Search Criteria:

  1. A server SHALL be capable of returning PractitionerRoles by Practitioner.identifier using:

    GET [base]/PractitionerRole?practitioner.identifier=[system]|[code]

  2. A server SHALL be capable of returning PractitionerRoles by Practitioner.family and Practitioner.given using:

    GET [base]/PractitionerRole?practitioner.family=[string]&given=[string]

  3. A server SHALL be capable of returning PractitionerRoles by specialty using:

GET [base]/PractitionerRole?specialty=[system]|[code]]

Search Parameters:

Conformance Parameter Type
SHALL practitioner.identifier reference + token
SHALL practitioner.family + practitioner.given reference + string + string
SHALL specialty token

Procedure

Supported Profiles: US Core Procedure Profile

Search Criteria:

  1. A server SHALL be capable of returning a patient’s procedures using: GET/Procedure?patient=[id]

  2. A server SHALL be capable of returning all of a patient’s procedures over a specified time period using: GET /Procedure?patient=[id]&date=[date]{&date=[date]}

Search Parameters:

Conformance Parameter Type Modifiers
SHALL patient reference
SHALL patient + date reference + date date modifiers‘ge’,‘le’,’gt’,’lt’