N.B. This is highly preliminary, not a commitment or final version of any particular API or data model. This is purely for internal collaboration and preview purposes.

Help us improve! You can correct errors or add to this page by clicking here to edit this page on Github.

The calls below are all written with respect to the base URL /. But any given SMART container will place all API calls its own base URL, e.g.

http://sample_smart_emr.com/smart-base/

Any individual item that can be retrieved via GET should have a fully-dereferenceable URI. To continue the example above, a medication in our sample EMR might have the URI:

http://sample_smart_emr.com/smart-base/records/123456/medications/664373

Changelog

Click here for the list of Changes to the API and Payloads for the latest release.

Overview

The SMART API provides access to individual resources (medications, fulfillment events, prescription events, problems, etc.) and groups of these resources in a RESTful API.

REST Design Principles

In general you can interact with a:

  • Group of resources using:
    • GET to retrieve a group of resources such as /medications/
  • Single resource using:
    • GET to retrieve a single resource such as /medications/{medication_id}

OWL Ontology File

The API calls listed below, as well as the RDF/XML payloads, are also defined in a machine-readable OWL file. The OWL file has been used to generate the documentation below, as well as our client-side REST libraries and API Playground app.

SMART REST API Reference

Each GET call in the SMART REST API is listed below and grouped by the "scope" or "access control category" the SMART container applies to the call. The SMART container implements this access control using the OAuth tokens passed in with each API request as described in the build a REST App howto.

Currently there are three "scopes" or access control categories:

  1. Container calls can be made by anyone against the container. Examples of this type of call are fetching the container's manifest and fetching the container's ontology. These calls need not be OAuth-signed (though it is not incorrect to sign them).

  2. Record calls are scoped to a (app, user, record) tuple e.g. calls to fetch a patient's medical record data. An example would be getting the medications in a patient's record. The OAuth credentials for the app (e.g. the consumer_key and consumer_secret) and previously fetched OAuth credentials from the server including the smart_record_id These calls must be signed as "3-legged" OAuth requests, meaning they are signed with a combination of the app's consumer token + access token.

  3. User calls are scoped to a (app, user) tuple and are used for setting a user's preferences for that app only. These calls are also signed as "3-legged" OAuth calls, using an app's consumer token + access token. (Future versions of the SMART API may allow an app to read another's preferences or add a "global" set of user preferences.)




Container Calls

App Manifest

  • URI: GET /apps/{descriptor}/manifest
  • Client method name: get_app_manifest

Returns a JSON SMART UI app manifest for the app matching {descriptor}, or 404. Note that {descriptor} can be an app ID like "got-statins

  • URI: GET /apps/manifests/
  • Client method name: get_app_manifests
Returns a JSON list of all SMART UI app manifests installed on the container.

App Manifest RDF

ContainerManifest

  • URI: GET /manifest
  • Client method name: get_container_manifest

Get manifest for a container

ContainerManifest RDF

Demographics

  • URI: GET /records/search
  • Client method name: search_records

Get an RDF graph of sp:Demographics elements for all patients that match the query. Matching treats family_name and given_name as the beginning of a name. For instance given_name='J' matches /^J/i and thus matchs 'Josh'. Date of birth is an ISO8601 string like "2008-03-21"; gender is "male" or "female". Gender, date_of_birth, zipcode, and medical_record_number must match exactly.

Demographics RDF

Ontology

  • URI: GET /ontology
  • Client method name: get_ontology

Get the ontology used by a SMART container

Ontology RDF

User

  • URI: GET /users/search
  • Client method name: search_users

Get users by name (or all users if blank)

  • URI: GET /users/{user_id}
  • Client method name: get_user
Get a single user by ID

User RDF

Record Calls

Allergy

  • URI: GET /records/{record_id}/allergies/
  • Client method name: get_allergies

Get all Allergies and Allergy Exclusions for a patient

  • URI: GET /records/{record_id}/allergies/{allergy_id}
  • Client method name: get_allergy
Get one Allergy for a patient

Allergy RDF

Clinical Note

  • URI: POST /records/{record_id}/clinical_notes/
  • Client method name: post_clinical_note

Post a Clinical Note for a patient. The body of the post should contain SMART RDF/XML serialization of the clinical note without the belongsTo predicate. The clinical note will be added to the collection of notes and the call will return a a copy of the posted data to indicate as successful posting.

  • URI: GET /records/{record_id}/clinical_notes/{clinical_note_id}
  • Client method name: get_clinical_note
Get one Clinical Note for a patient

  • URI: GET /records/{record_id}/clinical_notes/
  • Client method name: get_clinical_notes
Get all Clinical Notes for a patient

Clinical Note RDF

Demographics

  • URI: GET /records/{record_id}/demographics
  • Client method name: get_demographics

Get Demographics for a patient

Demographics RDF

Document

  • URI: GET /records/{record_id}/documents/{document_id}
  • Client method name: get_document

Allows a SMART app to request a single document. The optional format parameter sets the output format of the call. The possible values are metadata, raw, and combined. In format=metadata mode, the container returns metadata and desceriptors of the document in RDF-XML. In format=combined mode the call returns the serialized document content in addition to all the data from the format=metadata mode. In format=raw mode, SMART returns the raw document content with the proper MIME type. In the absence of a format parameter, the API defaults to format=raw.

  • URI: GET /records/{record_id}/documents/
  • Client method name: get_documents
Returns data about all the available documents for the patient record subject to the standard filter restrictions. The optional format parameter sets the output format of the call. The possible values are metadata and combined. In format=metadata mode, the container returns metadata and desceriptors of the documents in RDF-XML. In format=combined mode the call returns the serialized documents' content in addition to all the data from the format=metadata mode. In the absence of a format parameter, the API defaults to format=metadata.

Document RDF

Encounter

  • URI: GET /records/{record_id}/encounters/
  • Client method name: get_encounters

Get all Encounters for a patient

  • URI: GET /records/{record_id}/encounters/{encounter_id}
  • Client method name: get_encounter
Get one Encounter for a patient

Encounter RDF

Family History Observation

  • URI: GET /records/{record_id}/family_history/
  • Client method name: get_family_history_observations

Get all Family Histories for a patient

  • URI: GET /records/{record_id}/family_history/{family_history_id}
  • Client method name: get_family_history_observation
Get one Family History for a patient

Family History Observation RDF

Fulfillment

  • URI: GET /records/{record_id}/fulfillments/
  • Client method name: get_fulfillments

Get all Fulfillments for a patient

  • URI: GET /records/{record_id}/fulfillments/{fulfillment_id}
  • Client method name: get_fulfillment
Get one Fulfillment for a patient

Fulfillment RDF

Immunization

  • URI: GET /records/{record_id}/immunizations/{immunization_id}
  • Client method name: get_immunization

Get one Immunization for a patient

  • URI: GET /records/{record_id}/immunizations/
  • Client method name: get_immunizations
Get all Immunizations for a patient

Immunization RDF

Lab Panel

  • URI: GET /records/{record_id}/lab_panels/
  • Client method name: get_lab_panels

Get all Lab Panels for a patient

  • URI: GET /records/{record_id}/lab_panels/
  • Client method name: get_lab_panel
Get one Lab Panel for a patient

Lab Panel RDF

Lab Result

  • URI: GET /records/{record_id}/lab_results/{lab_result_id}
  • Client method name: get_lab_result

Get one Lab Result for a patient

  • URI: GET /records/{record_id}/lab_results/
  • Client method name: get_lab_results
Get all Lab Results for a patient

Lab Result RDF

Medication

  • URI: GET /records/{record_id}/medications/
  • Client method name: get_medications

Get all Medications for a patient

  • URI: GET /records/{record_id}/medications/{medication_id}
  • Client method name: get_medication
Get one Medication for a patient

Medication RDF

Photograph

  • URI: GET /records/{record_id}/photograph
  • Client method name: get_photograph

Get one Photograph for a patient

Photograph RDF

Problem

  • URI: GET /records/{record_id}/problems/{problem_id}
  • Client method name: get_problem

Get one Problem for a patient

  • URI: GET /records/{record_id}/problems/
  • Client method name: get_problems
Get all Problems for a patient

Problem RDF

Procedure

  • URI: GET /records/{record_id}/procedures/
  • Client method name: get_procedures

Get all Procedures for a patient

  • URI: GET /records/{record_id}/procedures/{procedure_id}
  • Client method name: get_procedure
Get one Procedure for a patient

Procedure RDF

Scratchpad Data

  • URI: GET /records/{record_id}/apps/{smart_app_id}/scratchpad
  • Client method name: get_scratchpad_data

Returns the scratchpad blob unicode data stored in the patient's account by a previous run of the owner app in the response body. An app can ready any other app's scratchpad. If not data is available the call will return an empty string.

  • URI: DELETE /records/{record_id}/apps/{smart_app_id}/scratchpad
  • Client method name: delete_scratchpad_data
Purges the scratchpad data stored in the SMART container for the selected app. If everything goes well, this call will respond with HTTP 200 status code.

  • URI: PUT /records/{record_id}/apps/{smart_app_id}/scratchpad
  • Client method name: put_scratchpad_data
Stores scratchpad data in the patient's account in the SMART container scoped to the current app. The HTTP request body represents the unicode-encoded data blob. The app chooses the best format for the data that makes sense for its use case (it is unstructured from SMART's perspective). If the data save was successful, the SMART server will respond with an HTTP 200 code and include the stored data in the response body. It is the app's responsibility to compare the response with the intended data content. If there are any discrepancies, then a concurrency problem occured while writing the data and the app should request a fresh copy of the scratchpad data stored on the server, merge it with its local copy and attempt writing it again.

Scratchpad Data RDF

Social History

  • URI: GET /records/{record_id}/social_history
  • Client method name: get_social_history

Get Social History for a patient

Social History RDF

Vital Sign Set

  • URI: GET /records/{record_id}/vital_sign_sets/
  • Client method name: get_vital_sign_sets

Get all Vital Sign Sets for a patient

  • URI: GET /records/{record_id}/vital_sign_sets/{vital_sign_set_id}
  • Client method name: get_vital_sign_set
Get one Vital Sign Set for a patient

Vital Sign Set RDF

User Calls

User Preferences

  • URI: DELETE /users/{user_id}/apps/{smart_app_id}/preferences
  • Client method name: delete_user_preferences

Purges the user preferences stored in the SMART container for the selected app. If everything goes well, this call will respond with HTTP 200 status code.

  • URI: PUT /users/{user_id}/apps/{smart_app_id}/preferences
  • Client method name: put_user_preferences
Stores preferences data in the user's account in the SMART container scoped to the current app. The HTTP request body represents the unicode-encoded data blob. The app chooses the best format for the data that makes sense for its use case (it is unstructured from SMART's perspective). If the data save was successful, the SMART server will respond with an HTTP 200 code and include the stored data in the response body. It is the app's responsibility to compare the response with the intended data content. If there are any discrepancies, then a concurrency problem occured while writing the data and the app should request a fresh copy of the preferences data stored on the server, merge it with its local copy and attempt writing it again.

  • URI: GET /users/{user_id}/apps/{smart_app_id}/preferences
  • Client method name: get_user_preferences
Returns the preferences blob unicode data stored in the user's account by a previous run of the app in the response body. If not data is available the call will return an empty string.

User Preferences RDF