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

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/{user_id}
• Client method name: get_user

Get a single user by ID

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

Record Calls

Allergy

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

Get one Allergy for a patient

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

Clinical Note

• URI: GET /records/{record_id}/clinical_notes/{clinical_note_id}
• Client method name: get_clinical_note

Get one Clinical Note for a patient

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

• URI: GET /records/{record_id}/clinical_notes/
• Client method name: get_clinical_notes

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

Get one Document for a patient

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

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

Family History Observation

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

Get one Family History for a patient

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

Fulfillment

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

Get one Fulfillment for a patient

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

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

Lab Panel

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

Get one Lab Panel for a patient

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

Lab Result

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

Get all Lab Results for a patient

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

Medication

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

Get one Medication for a patient

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

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/
• Client method name: get_problems

Get all Problems for a patient

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

Procedure

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

Get one Procedure for a patient

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

Scratchpad Data

• URI: PUT /records/{record_id}/apps/{smart_app_id}/scratchpad
• Client method name: put_scratchpad_data

Set new scratchpad data for an app

• URI: DELETE /records/{record_id}/apps/{smart_app_id}/scratchpad
• Client method name: delete_scratchpad_data

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

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

User Calls

User Preferences

• URI: GET /users/{user_id}/apps/{smart_app_id}/preferences
• Client method name: get_user_preferences

Get user preferences for an app

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

• URI: PUT /users/{user_id}/apps/{smart_app_id}/preferences
• Client method name: put_user_preferences