Sync For Science

Clinical Data

The API calls below show how to use S4S for sharing Clinical Data. You’ll see each data type annotated with its MU Common Clinical Data Set labels (#1-21). Note that we’re currently not covering elements #16 (care team members), #18 (unique device identifiers), #19 (assessment and plan of treatment), #20 (goals) — which we believe is a reasonable scope limitation for the S4S pilots.

The APIs are designed for compatibility with the Argonaut Project Data Query Implementation Guide, based on SMART on FHIR.

The examples below refer to the following variables:

patientId indicates the FHIR id of the Patient in context. For example, 123.
lastCheck indiclates a FHIR instant, with millisecond-level precision including a timezone. For example, 2016-04-01T02:52:32.000Z

We’ll also refer to two “request times”:

first-connection for broad queries that the app will make once, after first approval, to back-fill historical data
periodic-update for narrow queries the app will make frequently (e.g. weekly)

(Note: a production-quality app might repeat the “broad” queries on an occasional basis — e.g. yearly — as a sanity check, and to discovery any data that may have fallen out of the record.)

Want to propose a change? edit this page!

Authorization expectations: SMART on FHIR OAuth2

Sync for Science^TM (like Argonaut) uses the OAuth2-based SMART on FHIR authorization specification. But we don’t need all the moving parts. In particular, in Sync for Science we can get away with a minimum of:

“confidential clients”, meaning that apps get assigned a client_id and client_secret to authenticate to EHRs.The general SMART and Argonaut specs also require support for “public clients”, but it’s not strictly a requirement in S4S.
“standalone launch” flow, meaning that the patient (research participant) can begin by interacting with the PMI app, and from there, can launch into an “connect to my EHR” workflow. The general SMART and Argonaut specs also require support for the “EHR launch flow” (where apps launch from an EHR or portal), but it’s not strictly a requirement in S4S.
patient/*.read launch/patient offline_access scopes, meaning that when the app launches, it will ask the EHR for permission to read all data available to the patient, and it will ask to learn the FHIR id of the patient whose records are shared.

We also do not require support for Single Sign-on via OpenID Connect in S4S (though again, it’s part of SMART and Argonaut, and we encourage implementers to support it).

Server metadata

Return a FHIR capability statement with SMART extensions for OAuth

GET /metadata

Patient demographics (MU CCDS #1-6)

Includes: name, birth sex, birthdate, race, ethnicty, preferred language

Details	URL
Argonaut Guide	http://argonautwiki.hl7.org/index.php?title=Patient
FHIR DSTU2 Resource	http://hl7.org/fhir/DSTU2/patient.html#resource

On first-connection, periodic-update.

GET /Patient/{{patientId}}

Request

GET /api/open-fhir/Patient/smart-1288992 HTTP/1.1
Host: portal.demo.syncfor.science
Accept: application/json+fhir

Response

Smoking status (MU CCDS #7)

Details	URL
Argonaut Guide	http://argonautwiki.hl7.org/index.php?title=Smoking_Status
FHIR DSTU2 Resource	http://hl7.org/fhir/DSTU2/observation.html#resource

On first-connection

GET /Observation?category=social-history&patient={{patientId}}

Request

GET /api/open-fhir/Observation?category=social-history&patient=smart-1288992 HTTP/1.1
Host: portal.demo.syncfor.science
Accept: application/json+fhir

Response

On periodic-update

GET /Observation?category=social-history&patient={{patientId}}&_lastUpdated=gt{{lastCheck}}

Request

GET /api/open-fhir/Observation?category=social-history&patient=smart-1288992&_lastUpdated=gt2016-04-16 HTTP/1.1
Host: portal.demo.syncfor.science
Accept: application/json+fhir

Response

Problems (MU CCDS #8, #21)

Details	URL
Argonaut Guide	http://argonautwiki.hl7.org/index.php?title=Problems_and_Health_Concerns
FHIR DSTU2 Resource	http://hl7.org/fhir/DSTU2/condition.html#resource

On first-connection

GET /Condition?patient={{patientId}}

Request

GET /api/open-fhir/Condition?patient=smart-1288992 HTTP/1.1
Host: portal.demo.syncfor.science
Accept: application/json+fhir

Response

On periodic-update

GET /Condition?patient={{patientId}}&_lastUpdated=gt{{lastCheck}}

Request

GET /api/open-fhir/Condition?patient=smart-1288992&_lastUpdated=gt2016-04-17T04:00:00 HTTP/1.1
Host: portal.demo.syncfor.science
Accept: application/json+fhir

Response

Medications and allergies (MU CCDS #9-10)

Details	URL
Argonaut Guide	http://argonautwiki.hl7.org/index.php?title=Medications http://argonautwiki.hl7.org/index.php?title=Allergies
FHIR DSTU2 Resource	http://hl7.org/fhir/DSTU2/medicationstatement.html#resource http://hl7.org/fhir/DSTU2/medicationorder.html#resource http://hl7.org/fhir/DSTU2/medicationdispense.html#resource http://hl7.org/fhir/DSTU2/medicationadministration.html#resource http://hl7.org/fhir/DSTU2/allergyintolerance.html#resource

On first-connection

GET /MedicationOrder?patient={{patientId}}

Request

GET /api/open-fhir/MedicationOrder?patient=smart-1288992&_count=1 HTTP/1.1
Host: portal.demo.syncfor.science
Accept: application/json+fhir

Response

GET /MedicationStatement?patient={{patientId}}

Request

GET /api/open-fhir/MedicationStatement?patient=smart-1288992&_count=1 HTTP/1.1
Host: portal.demo.syncfor.science
Accept: application/json+fhir

Response

GET /MedicationDispense?patient={{patientId}}

Request

GET /api/open-fhir/MedicationDispense?patient=smart-1288992&_count=1 HTTP/1.1
Host: portal.demo.syncfor.science
Accept: application/json+fhir

Response

GET /MedicationAdministration?patient={{patientId}}

Request

GET /api/open-fhir/MedicationAdministration?patient=smart-1288992&_count=1 HTTP/1.1
Host: portal.demo.syncfor.science
Accept: application/json+fhir

Response

GET /AllergyIntolerance?patient={{patientId}}

Request

GET /api/open-fhir/AllergyIntolerance?patient=smart-1288992&_count=1 HTTP/1.1
Host: portal.demo.syncfor.science
Accept: application/json+fhir

Response

On periodic-update

GET /MedicationOrder?patient={{patientId}}&_lastUpdated=gt{{lastCheck}}
GET /MedicationStatement?patient={{patientId}}&_lastUpdated=gt{{lastCheck}}
GET /MedicationDispense?patient={{patientId}}&_lastUpdated=gt{{lastCheck}}
GET /MedicationAdministration?patient={{patientId}}&_lastUpdated=gt{{lastCheck}}
GET /AllergyIntolerance?patient={{patientId}}&_lastUpdated=gt{{lastCheck}}}

Lab results (MU CCDS #11? and #12)

Details	URL
Argonaut Guide	http://argonautwiki.hl7.org/index.php?title=Laboratory_Results
FHIR DSTU2 Resource	https://hl7.org/fhir/DSTU2/observation.html#resource

On first-connection

GET /Observation?category=laboratory?patient={{patientId}}

Request

GET /api/open-fhir/Observation?category=laboratory&patient=smart-1288992&_count=5 HTTP/1.1
Host: portal.demo.syncfor.science
Accept: application/json+fhir

Response

On periodic-update

GET /Observation?category=laboratory?patient={{patientId}}&_lastUpdated=gt{{lastCheck}}

Vital signs (MU CCDS #13)

Details	URL
Argonaut Guide	http://argonautwiki.hl7.org/index.php?title=Vital_Signs
FHIR DSTU2 Resource	https://hl7.org/fhir/DSTU2/observation.html#resource

On first-connection

GET /Observation?category=vital-signs?patient={{patientId}}

Request

GET /api/open-fhir/Observation?category=vital-signs&patient=smart-1288992&_count=5 HTTP/1.1
Host: portal.demo.syncfor.science
Accept: application/json+fhir

Response

On periodic-update

GET /Observation?category=vital-signs?patient={{patientId}}&_lastUpdated=gt{{lastCheck}}

Procedures (MU CCDS #15)

Details	URL
Argonaut Guide	http://argonautwiki.hl7.org/index.php?title=Procedures
FHIR DSTU2 Resource	https://hl7.org/fhir/DSTU2/procedure.html#resource

On first-connection

GET /Procedure?patient={{patientId}}

Request

GET /api/open-fhir/Procedure?patient=smart-1288992 HTTP/1.1
Host: portal.demo.syncfor.science
Accept: application/json+fhir

Response

On periodic-update

GET /Procedure?patient={{patientId}}&_lastUpdated=gt{{lastCheck}}}

Immunizations (MU CCDS #17)

Details	URL
Argonaut Guide	http://argonautwiki.hl7.org/index.php?title=Immunizations
FHIR DSTU2 Resource	https://hl7.org/fhir/DSTU2/immunization.html#resource

On first-connection

GET /Immunization?patient={{patientId}}

Request

GET /api/open-fhir/Immunization?patient=smart-1288992 HTTP/1.1
Host: portal.demo.syncfor.science
Accept: application/json+fhir

Response

On periodic-update

GET /Immunization?patient={{patientId}}&_lastUpdated=gt{{lastCheck}}

Patient documents

That is: whatever is available for portal download — not a CCDS requirement

Details	URL
Argonaut Guide	http://argonautwiki.hl7.org/index.php?title=Argonaut_Document_Access
FHIR DSTU2 Resource	https://hl7.org/fhir/DSTU2/documentreference.html#resource

On first-connection

GET /DocumentReference?patient={{patientId}}

Request

GET /api/open-fhir/DocumentReference?patient=smart-1288992 HTTP/1.1
Host: portal.demo.syncfor.science
Accept: application/json+fhir

Response

On periodic-update

GET /DocumentReference?patient={{patientId}}&_lastUpdated=gt{{lastCheck}}