mock fhir api

Build the future of healthcare now with the Catalyze Mock FHIR API

The Catalyze FHIR Docs describe FHIR's models and APIs, while showing examples throughout. We encourage contributions and adaptations to this project. A pre-requisite to that is to make this repository open. In addition to our documentation is a mock FHIR API. With this you can build and prototype applications for use with the origin FHIR spec.

Your API Key has been emailed to you. Check out the API page to start prototyping.

Sections

An Introduction to FHIR

FHIR (Fast Healthcare Interoperability Resources) is a new and emerging standard being developed under the auspices of the Health Language 7 (HL7) organization. Pronounced as ‘Fire’, it was initially developed by Graham Grieve, who insisted that FHIR be open sourced. At it’s core, FHIR is intended to be the next generation of healthcare interoperability. It tries to combine the best features of HL7 Version 2 and Version 3, in which Grieve was significantly involved.

Why FHIR?

The current state-of-the-art in healthcare integration and interoperability is based on HL7, and is a serious mess. Organizations today spend upwards of $5,000 to $10,000 per HL7 interface, not to mention serious licensing fees to implement and use integration engines. All of which raise the interesting question of, “Wait, if they are all based on a standard, why do I need an integration engine?” Well, because of two reasons:

  1. HL7 is a standard but it is not an open standard. You need to be a member of the HL7 organization and pay fees before using the content in any commerical fashion.
  2. HL7 is an ancient standard: Wikipedia notes that it was developed in the late 80s when a lot of things we take for granted now didn’t exist - mobile numbers, emails, NPIs (national provider identifiers), APIs…

What resulted was a lot of “I’ll just do it this way”, causing an explosion of HL7 variants. This, in turn, led to the need for interface engines where additional logic needs to be coded to accommodate those “this-way” variants and other healthcare specific use cases. That led to the bigger problem that integration and logic are now embedded into the data transformation process. Change your source system (upgrade, replace, etc.) and your integration falls apart. Need more data than you’re currently getting? Well, it’s back to the integration engine again. Oh, by the way, there is no concept of CI / CD (continuous integration, continuous deployment) in the context of integration engines. A lot of the time developers make changes in production directly, which is also why healthcare institutions are very cautious about providing access to systems sending data to any external system, no matter the value, and for good reason.

A better, more modern approach to integration and interoperability

FHIR has an ambitious goal. Integration capabilities should be built into the EHR itself along with the other aspects of authentication and security. This will, over time, eliminate the need for expensive integration projects and licenses; this is the goal at least. Additionally, the use of modern concepts such as RESTful APIs and accompanying documentation will make it much easier for developers and applications to quickly connect and get the data needed. From a design perspective, the general principle is that since healthcare is complicated, creating a standard set of models which are transactional in nature (like HL7) has shown to be problematic; therefore, creating core models (like patients, for example), and having standardized data models around those core elements, and ensuring that most, if not all, use cases can be addressed will allow requests to be composed as needed.

Given the above, FHIR does offer many improvements over existing standards:

  • It’s open source: This is a big deal and the first effort in making healthcare integration more transparent and accessible. Putting it out in the open has created a significant community including developers, vendors and enterprises.
  • RESTful: REST-based design brings a significant amount of benefit, namely that an API that adheres to the principles of REST does not require the client to know anything about the structure of the API. Rather, the server needs to provide whatever information the client needs to interact with the service.
  • Extensible: Extensibility under the RESTful context ensures that additions can be easily tacked on to cover specific use cases without impacting the core models.
  • Composable: Composability ensures that almost any request can be cobbled together using the core models / resources and associated extensions.
  • Good documentation: This is unique and perhaps since driven by the RESTful API approach, good documentation results as a byproduct. A playable version of the FHIR APIs would be a nice to have and is something that we, at Catalyze, intend to provide as part of this documentation.
  • Support for modern web standards: XML, JSON, HTTP, Atom, OAuth, REST - these are the underlying technologies that FHIR leverages. They are battle tested and have been proven at scale and under significant security requirements.

Flexibility without modifying underlying systems or integration engines

As described earlier, one of the biggest challenges in the older integration standards that were implemented is that any extensions required to support various healthcare workflows were force fitted into the standard (e.g. z-segments in HL7). This meant code changes on the underlying systems to generate these specific sets of data and additional work on the integration engine to support the processing of this data. All this made it very cumbersome to create and manage integrations with any changes in the underlying source systems (e.g. upgrades etc.), causing a significant amount of rework.

FHIR addresses this by:

  • Focusing on ease of implementation: This is very different from most standards where the focus is more on coverage and data models. FHIR is interesting in that the focus has been on ease of implementation right from the beginning, including backwards compatibility. Multiple implementation libraries have also been provided in Java, .NET, etc. along with many examples to kick-start development. The website claims that “multiple developers had simple interfaces working in a single day,” which is unheard of in healthcare.
  • Easy extensibility: FHIR solves this challenge by defining a simple framework for extending and adapting the existing resources. All systems, no matter how they are developed, can easily read these extensions and extension definitions can be retrieved using the same framework as retrieving other resources.
  • Human readability: HL7 3.0 had a concept of a human readable version of the document / data being shared to ensure that developers or clinicians could still read the source data to eliminate any potential of misconfiguration or coding errors. FHIR borrows this concept as well. Every resource carries a human-readable text representation using html as a fallback display option. This is particularly important for complex clinical information where many systems take a simple textual/document based approach.

Advantages over existing standards e.g. HL7

  • Pipe delimited vs. JSON, XML…: No further discussion is required. This approach makes it more easily usable, understandable and testable.
  • Security: HL7 as a protocol doesn’t have security and authentication built into it. To be fair, HL7 was always meant to enable intra-system communication i.e. communicate between lab systems and EHR etc. All of which were within a health system’s firewalls. Therefore, authentication wasn’t really needed. The evolution of healthcare has made care delivery more dispersed, which is why HL7 is beginning to show its gaps. FHIR leverages (or is in the process of defining) modern https based authentication and authorization capabilities such as OAuth, which are prevalent in the modern web and have been battle tested over the years.
  • Flexible and composable: Essentially, the FHIR design allows developers to combine requests to create any interface or extended resources (with associated definition) and “tack” them onto pre-defined resource models. No coding up the underlying systems or touching interface engines required.

Status and challenges

FHIR is still a work in progress. It does have a few advantages.

  • Significant industry support: Apart from individual developers and other organizations working and contributing sample implementations (for example - HAPI-FHIR and many more), a significant group of enterprises have come together under the auspices of HL7 with the moniker of “Argonaut Project”. This group includes EHR vendors and health systems such as
    • athenahealth
    • Beth Israel Deaconess Medical Center
    • Cerner
    • Epic
    • Intermountain Healthcare
    • Mayo Clinic
    • Meditech
    • McKesson
    • Partners HealthCare System
    • SMART at the Boston Children’s Hospital Informatics Program
    • The Advisory Board Company
  • It’s a work in progress: Despite significant industry support, it is unlikely that widespread implementations of FHIR will be seen until around the 2016-2017 timeframe. This is because definitions and specifications are still in progress, implementations are still underway and it is likely that this might also require EHR software changes.
  • Security is still an open item: There are a lot of things to be figured out around security with FHIR. Authentication before authorization or vice versa? Conformance and associated profiles per link? Is there to be an API route to call to verify that? Is that route open to everyone?
  • Not real-time: This is the biggest gap currently. HL7 was always a realtime protocol. If someone was admitted to the hospital, all relevant parties were notified immediately via ADT. FHIR is currently still a request based protocol - you ask if you need to know something such as “Was this person admitted to the hospital?”. This makes sense from a patient app perspective, not so much from a workflow perspective. Webhooks can definitely be added on, but this begs the questions, “Well - why can’t we just FHIR enable HL7?” and the Catalyze answer is, “Yes, indeed. It should.”
  • Granular resource model can become request intensive: ADT (and other HL7) messages were crafted with care to support hospital and ancillary system workflows. The flexibility and composability (described in the advantages section above) come at a cost. To get all the data that one normally expects from an ADT message would require a “bundle” of FHIR resources. This could get complicated and request-intensive quickly.

Overall, FHIR has a lot going for it. There are gaps, but they are neither unexpected nor insurmountable.

Intent of this FHIR documentation

As we worked with FHIR, one of the big challenges we found was navigating and understanding the FHIR resources and other models. To help us and our engineering teams better understand FHIR, we documented it here. We open sourced this documentation so that others could benefit as well, accelerating the understanding of FHIR and allowing for faster development of tools and services that leverage FHIR.

Note: that this is not meant to replace the HL7 FHIR pages. Those pages will still be the authoritative source. We will attempt to keep this page up to date as best we can. It would be great if the community could pitch in to keep this documentation updated, which is the other reason for open sourcing this material. In addition, we will in time provide test data corresponding to each of the resource and other objects defined in the latest FHIR DSTU spec: DSTU 1 (v0.0.82); if you’re interested in helping with this process, please reach out. As mentioned earlier, this repo will be open sourced so any pull requests are welcome.

The Github repo will be made available shortly. <!–here –>

The design of FHIR and it’s building blocks

This section provides an in-depth look at the design of FHIR. It provides an overview of the core building blocks of the FHIR specification - the Resource object, and the various categories of resource objects with a few examples.

Quote from FHIR website: FHIR solutions are built from a set of modular components called “Resources”. These resources can easily be assembled into working systems that solve real world clinical and administrative problems at a fraction of the price of existing alternatives. FHIR is suitable for use in a wide variety of contexts – mobile phone apps, cloud communications, EHR-based data sharing, server communication in large institutional healthcare providers, and much more.

At the core of the design of FHIR is the concept of a Resource. Resources are essentially a structured model of a JSON or XML object. There are various categories of resources, namely:

  • Clinical Resources: These are models that describe clinical objects such as Medications, Diagnostics, Observations or other General objects.
  • Administrative Resources: These are models that are used to describe objects that the clinical resources can be attributed to (Attribution), are descriptive (Entities), or are used to create or support workflows (Workflow).
  • Infrastructure Resources: These are models that pertain to carrying specific data payloads such as documents, message headers specifying source and destinations, and more. Critically, there are four key models described in this category:

    • Composition: these allow one to combine various other resources into a single, complex and more descriptive object.
    • Query: these are requests and responses which define a structure for querying for various data elements and an associated structure for returning responses.
    • Profiles: these are intended to be a self-descriptive way to define what models and extensions are supported by the specific implementation and the associated models. This is also where model extensions can be specified to extend other models to support specific needs.
    • Value Sets: these are useful since they addresses one of the biggest challenges in healthcare. Different health systems use different value sets and the challenge with interoperability has exacerbated because of these differences. This model allows each implementation to specify the value sets in use to assure symantic interoperability.

Putting these various models together allows for the creation of most any clinical condition.

Structure of any Resource

All resources follow a standard model with content and associated extensions being the only thing that changes from resource to resource. All that means is that while a Patient Resource and a Medication Resource both have the same general overall structure, the content within each describing the resource will be different and specific to that resource.

The general structure of any Resource is as follows:

  • Resource Type: this identifies the specific resource model i.e. Patient, Medications, Allergies, etc.
  • Human Readable summary section: this is an XHTML section that provides a human readable version of the content within the message. This can be considered as a backup as well as a verification section.
  • Identifier section: this is a unique identifier URL for each resource identifying to be of a specific type e.g. Patient.
  • Extension section: this allows for the definition of any extension that might be required to support specific clinical workflows e.g. clinical trial applicability. This can be inserted in any section to cover specific use cases and workflow needs.
  • Contained Resources: these are other resources used in identification and transaction processing e.g. message header and the data object corresponding to the type identified earlier or images associated with the patient such as an avatar.
  • Resource content: this is the core content of the resource. In the case of a patient, it contains all relevant details about that patient such as name, address, phone, guardian or other contact info and so on. Each resource has a defined data model.
  • Tags: such as security labels which can include ACLs, workflow specific functions, etc. This one is still murky and should be considered under development.

Let’s take a sample Resource and work our way through it. We’ll lay out the individual sections and describe them and finally put it all together (with all the accompanying curly braces, indentations and commas, etc. added on) to see what the complete Resource will look like. Let’s take a Patient Resource as an example.

Resource Type

Every resource will start with its name. Given that we’re taking the example of a Patient, the resource object will start with

"resourceType": "Patient"

This sets the context of the data exchange and allows for appropriate parsing and other rules to be invoked.

Human Readable Summary

Every resource also has associated with it a tabular (and thus human readable) description of the contents of the message. The contents of this section are in XHTML format and will include all the \n (next line) characters. A sample human readable summary included in a patient message could look like this:

  "text": {
      "status": "generated",
      "div": "<div>
    <table> \n
      <tbody> \n
        <tr> \n
          <td>Name</td>  \n
          <td>John Samuel <b>Appleseed</b> (&quot;John&quot;)</td>  \n
        </tr>  \n
        <tr>  \n
          <td>Address</td> \n
          <td>1231 Evergreen Ave, #30, San Francisco, CA 90002</td>  \n
        </tr>  \n
        <tr> \n
          <td>Contacts</td> \n
          <td>Home: unknown. Work: (203) 5555 6473, Name: Bénédicte du Marché. Relationship: Partner. Phone: +33 (237) 998327</td> \n
        </tr> \n
        <tr> \n
          <td>Gender</td> \n
          <td>Male</td> \n
        </tr> \n
        <tr> \n
          <td>Birthdate</td> \n
          <td>1974-12-25</td> \n
        </tr> \n
        <tr> \n
          <td>Marital Status</td> \n
          <td>Married</td> \n
        </tr> \n
        <tr> \n
          <td>Multiple Birth Count</td> \n
          <td>3</td> \n
        </tr>  \n
        <tr> \n
          <td>Id</td> \n
          <td>MRN: 12345 (Acme Healthcare)</td> \n
        </tr> \n
      </tbody> \n
    </table> \n
</div>"
    }

Which could be easily parsed and made readable. In this case, the parsed / rendered content would look like this:

Name John Samuel Appleseed (“John”)
Address 1231 Evergreen Ave, #30, San Francisco, CA 90002
Contacts Home: unknown. Work: (203) 5555 6473, Name: Bénédicte du Marché. Relationship: Partner. Phone: +33 (237) 998327
Gender Male
Birthdate 1974-12-25
Marital Status Married
Multiple Birth Count 3
Id MRN: 12345 (Acme Healthcare)

The intent of this section is borrowed from the HL7 spec. The human readable version of the FHIR content serves two purposes: 1. Testing from a developer perspective is simplified as the developer now knows exactly what the message / transaction is supposed to communicate. 2. Overcoming errors in processing so that even if the message gets garbled for some reason, the human readable version is always available as a fallback for clinicians and others performing care.

Note that this narrative element in a resource is not mandatory. If you have to put one in, it SHALL reflect all the content needed for a human to understand the essential clinical and business information otherwise encoded within the resource. Note also that this is generally going to be difficult to generate. So, Epic for example, has chosen to drop this section from their spec for the time being. We expect a similar trend across various EHRs so practical deployments can (for the time being) safely skip this.

Identifier section

In FHIR, every object is expected to have its own URI (universal resource identifier). All this implies is that every patient (in our context) will have their own URI (and potentially URL) with a unique identifier. Identifiers could include SSN (social security numbers), MRNs (medical record numbers), and any number of others. Multiple identifiers can be specified since it is defined as an array. In our context, this would look like the following.

"identifier": [
    {
      "use": "usual",
      "label": "MRN",
      "system": "urn:oid:1.2.36.146.595.217.0.1",
      "value": "12345",
      "period": {
        "start": "2001-05-06"
      },
      "assigner": {
        "display": "Acme Healthcare"
      }
    }
  ]

Extensions

This is healthcare after all. There are a million use cases that you can think of that require “slightly” different definitions than what is already provided. Not to mention that since FHIR is supposed to be a universal standard, all of these must be taken into account as well. Hence the need for extensions.

Extensions can be tacked on to any resource object as long as they follow a specified format. The general format specified is as follows:

"name" : {
  "extension: [
    {
      "url" : "https://{{url.defining.extension-profile.com/id}}",
      "valueCode" : "{{value}}"
     }]
  "text": "{{human readable value - this is optional}}"/>
}

Let’s take a couple of use cases

Marital Status

"_maritalStatus": {"extension": [{
      "valueCode": "Common-law",
      "url": "http://fhir-endpoint.someorg.com/fhir/version1.0/marriage-extension#cl"
  }]}

Clinical Trials

Here’s another extremely relevant example of a patient resource where you can see an extension specific to a clinical trial including data elements such as trial status, profile with the trial status code, date, and the physician recording the results of the study.

  "resource-type" : "Patient",
  "extension" : [
    {
      "url" : "http://fhir-endpoint.someorg.com/fhir/version1.0/Profile/clinical-trails#trial-status",
      "extension" : [
        {
          "url" : "http://fhir-endpoint.someorg.com/fhir/version1.0/Profile/clinical-trails#trial-status#trial-status-code",
          "valueCode" : "Started"
        },
        {
          "url" : "http://fhir-endpoint.someorg.com/fhir/version1.0/Profile/clinical-trails#trial-status#trial-status-date",
          "valueDate" : "2015-02-26"
        },
        {
          "url" : "http://fhir-endpoint.someorg.com/fhir/version1.0/Profile/clinical-trails#trial-status#trial-status-who",
          "valueResource" : {
            "reference" : "Practitioner/f6dbc2f3-d054-4dd7-84c1-5e675f8e50d7"
          }
        }
     ]
   }
  ],
  ... other data for patient...

Contained Resources

Contained resources are a way to minimize the number of calls to be made (since FHIR is a request based format) so to address use cases where specific data elements need to be served up every time, a request is made to a particular resource. An example would be if a patient avatar picture needs to be served up anytime a patient resource is returned. Note that this assumes that the request is valid and the request is authenticated and authorized before the response is served.

In this specific scenario, if the patient avatar image always has to be sent along with any patient resource request, then it would look something like this

  "contained": [
      {
          "resourceType": "Binary",
          "id": "pic1",
          "contentType": "image/gif",
          "content": "R0lGODlhEwARAPcAAAAAAAAA/+9aAO+1AP/WAP/eAP/eCP/eEP/eGP/nAP/nCP/nEP/nIf/nKf/nUv/nWv/vAP/vCP/vEP/vGP/vIf/vKf/vMf/vOf/vWv/vY//va//vjP/3c//3lP/3nP//tf//vf///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////yH5BAEAAAEALAAAAAATABEAAAi+AAMIDDCgYMGBCBMSvMCQ4QCFCQcwDBGCA4cLDyEGECDxAoAQHjxwyKhQAMeGIUOSJJjRpIAGDS5wCDly4AALFlYOgHlBwwOSNydM0AmzwYGjBi8IHWoTgQYORg8QIGDAwAKhESI8HIDgwQaRDI1WXXAhK9MBBzZ8/XDxQoUFZC9IiCBh6wEHGz6IbNuwQoSpWxEgyLCXL8O/gAnylNlW6AUEBRIL7Og3KwQIiCXb9HsZQoIEUzUjNEiaNMKAAAA7"
      },
      {
          "resourceType": "Organization",
          "id": "org3141",
          "text": {
              "status": "generated",
              "div": "<div>\n      <p>Good Health Clinic<\/p>\n    <\/div>"
          },
          "identifier": [{
              "system": "urn:ietf:rfc:3986",
              "value": "2.16.840.1.113883.19.5"
          }],
          "name": "Good Health Clinic"
      }
  ]

Resource Content

This is the meat of the FHIR message. Every resource has a model associated with it. This is different based upon the resource type in question. As you can imagine, in the context of a patient, the kind of information that needs to be shared includes date of birth, contact information, next of kin, address info etc. The sample below is pretty self explanatory.

  "extension":
        {
            "url": "http://hl7.org/fhir/example-do-not-use#Patient.avatar",
            "valueResource": {
                "reference": "#pic1",
                "display": "Duck image"
            },
        },
  "name": [
    {
      "use": "official",
      "family": [
        "Chalmers"
      ],
      "given": [
        "Peter",
        "James"
      ]
    },
    {
      "use": "usual",
      "given": [
        "Jim"
      ]
    }
  ],
  "telecom": [
    {
      "use": "home"
    },
    {
      "system": "phone",
      "value": "(203) 5555 6473",
      "use": "work"
    }
  ],
  "gender": {
    "coding": [
      {
        "system": "http://hl7.org/fhir/v3/AdministrativeGender",
        "code": "M",
        "display": "Male"
      }
    ]
  },
  "birthDate": "1974-12-25",
  "deceasedBoolean": false,
  "address": [
    {
      "use": "home",
      "line": [
        "Evergreen Ave, #30"
      ],
      "city": "San Francisco",
      "state": "CA",
      "zip": "90002"
    }
  ],
  "_maritalStatus": {"extension": [{
      "valueCode": "ASKU",
      "url": "http://hl7.org/fhir/Profileiso-21090#nullFlavor"
  }]},
  "multipleBirthInteger": 3,
  "contained": [
      {
          "resourceType": "Binary",
          "id": "pic1",
          "contentType": "image/gif",
          "content": "R0lGODlhEwARAPcAAAAAAAAA/+9aAO+1AP/WAP/eAP/eCP/eEP/eGP/nAP/nCP/nEP/nIf/nKf/nUv/nWv/vAP/vCP/vEP/vGP/vIf/vKf/vMf/vOf/vWv/vY//va//vjP/3c//3lP/3nP//tf//vf///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////yH5BAEAAAEALAAAAAATABEAAAi+AAMIDDCgYMGBCBMSvMCQ4QCFCQcwDBGCA4cLDyEGECDxAoAQHjxwyKhQAMeGIUOSJJjRpIAGDS5wCDly4AALFlYOgHlBwwOSNydM0AmzwYGjBi8IHWoTgQYORg8QIGDAwAKhESI8HIDgwQaRDI1WXXAhK9MBBzZ8/XDxQoUFZC9IiCBh6wEHGz6IbNuwQoSpWxEgyLCXL8O/gAnylNlW6AUEBRIL7Og3KwQIiCXb9HsZQoIEUzUjNEiaNMKAAAA7"
      },
      {
          "resourceType": "Organization",
          "id": "org3141",
          "text": {
              "status": "generated",
              "div": "<div>\n      <p>Good Health Clinic<\/p>\n    <\/div>"
          },
          "identifier": [{
              "system": "urn:ietf:rfc:3986",
              "value": "2.16.840.1.113883.19.5"
          }],
          "name": "Good Health Clinic"
      }
  ],
  "contact": [
    {
      "relationship": [
        {
          "coding": [
            {
              "system": "http://hl7.org/fhir/patient-contact-relationship",
              "code": "partner"
            }
          ]
        }
      ],
      "name": {
        "family": [
          "du",
          "Marché"
        ],
        "_family": [
          {
            "extension": [
              {
                "url": "http://hl7.org/fhir/Profile/iso-21090#qualifier",
                "valueCode": "VV"
              }
            ]
          },
          null
        ],
        "given": [
          "Bénédicte"
        ]
      },
      "telecom": [
        {
          "system": "phone",
          "value": "+33 (237) 998327"
        }
      ]
    }
  ],
  "managingOrganization": {
    "reference": "Organization/1"
  },
  "active": true

There are other elements of a resource such as tags, metadata etc. which aren’t quite as well defined. We’ll delve into those in more detail subsequently.

Putting all the points of our discussion together thus far, here’s what the final Patient Resource showing the above sections will look like in the aggregate.

{
  "resourceType": "Patient",
  "text": {
    "status": "generated",
    "div": "<div>\n
    <table>\n <tbody>\n <tr>\n
        <td>Name</td>\n <td>John Samuel <b>Appleseed</b> (&quot;John&quot;)</td>\n
    </tr>\n <tr>\n <td>Address</td>\n
    <td>Evergreen Ave, #30, San Francisco, CA 90002 </td>\n </tr>\n <tr>\n
    <td>Contacts</td>\n <td>Home: unknown. Work: (203) 5555 6473</td>\n
</tr>\n <tr>\n <td>Id</td>\n
<td>MRN: 12345 (Acme Healthcare)</td>\n </tr>\n
</tbody>\n </table>\n </div>"
  },
  "identifier": [
    {
      "use": "usual",
      "label": "MRN",
      "system": "urn:oid:1.2.36.146.595.217.0.1",
      "value": "12345",
      "period": {
        "start": "2001-05-06"
      },
      "assigner": {
        "display": "Acme Healthcare"
      }
    }
  ],
  "extension": [
        {
            "url": "http://hl7.org/fhir/example-do-not-use#Patient.avatar",
            "valueResource": {
                "reference": "#pic1",
                "display": "Duck image"
            }
        },
  "name": [
    {
      "use": "official",
      "family": [
        "Chalmers"
      ],
      "given": [
        "Peter",
        "James"
      ]
    },
    {
      "use": "usual",
      "given": [
        "Jim"
      ]
    }
  ],
  "telecom": [
    {
      "use": "home"
    },
    {
      "system": "phone",
      "value": "(203) 5555 6473",
      "use": "work"
    }
  ],
  "gender": {
    "coding": [
      {
        "system": "http://hl7.org/fhir/v3/AdministrativeGender",
        "code": "M",
        "display": "Male"
      }
    ]
  },
  "birthDate": "1974-12-25",
  "deceasedBoolean": false,
  "address": [
    {
      "use": "home",
      "line": [
        "Evergreen Ave, #30"
      ],
      "city": "San Francisco",
      "state": "CA",
      "zip": "90002"
    }
  ],
  "_maritalStatus": {"extension": [{
      "valueCode": "ASKU",
      "url": "http://hl7.org/fhir/Profileiso-21090#nullFlavor"
  }]},
  "multipleBirthInteger": 3,
  "contained": [
      {
          "resourceType": "Binary",
          "id": "pic1",
          "contentType": "image/gif",
          "content": "R0lGODlhEwARAPcAAAAAAAAA/+9aAO+1AP/WAP/eAP/eCP/eEP/eGP/nAP/nCP/nEP/nIf/nKf/nUv/nWv/vAP/vCP/vEP/vGP/vIf/vKf/vMf/vOf/vWv/vY//va//vjP/3c//3lP/3nP//tf//vf///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////yH5BAEAAAEALAAAAAATABEAAAi+AAMIDDCgYMGBCBMSvMCQ4QCFCQcwDBGCA4cLDyEGECDxAoAQHjxwyKhQAMeGIUOSJJjRpIAGDS5wCDly4AALFlYOgHlBwwOSNydM0AmzwYGjBi8IHWoTgQYORg8QIGDAwAKhESI8HIDgwQaRDI1WXXAhK9MBBzZ8/XDxQoUFZC9IiCBh6wEHGz6IbNuwQoSpWxEgyLCXL8O/gAnylNlW6AUEBRIL7Og3KwQIiCXb9HsZQoIEUzUjNEiaNMKAAAA7"
      },
      {
          "resourceType": "Organization",
          "id": "org3141",
          "text": {
              "status": "generated",
              "div": "<div>\n      <p>Good Health Clinic<\/p>\n    <\/div>"
          },
          "identifier": [{
              "system": "urn:ietf:rfc:3986",
              "value": "2.16.840.1.113883.19.5"
          }],
          "name": "Good Health Clinic"
      }
  ],
  "contact": [
    {
      "relationship": [
        {
          "coding": [
            {
              "system": "http://hl7.org/fhir/patient-contact-relationship",
              "code": "partner"
            }
          ]
        }
      ],
      "name": {
        "family": [
          "du",
          "Marché"
        ],
        "_family": [
          {
            "extension": [
              {
                "url": "http://hl7.org/fhir/Profile/iso-21090#qualifier",
                "valueCode": "VV"
              }
            ]
          },
          null
        ],
        "given": [
          "Bénédicte"
        ]
      },
      "telecom": [
        {
          "system": "phone",
          "value": "+33 (237) 998327"
        }
      ]
    }
  ],
  "managingOrganization": {
    "reference": "Organization/1"
  },
  "active": true
}

Summary

Some FHIR resources are still in definition and open to comment. Some are still being defined - such as Financial models, which will fall under the Administrative category of Resources. The above sections delve into a little bit more detail on the overall resource model and its constituent parts.

Every resource consists of the following:

  • Identifier section: This is a unique identifier URL for each resource identifying the resource to be of a specific type e.g. patient. This is a required component.
  • Human Readable summary section: This is an XHTML section that provides a human readable version of the content within the message. This can be considered as a backup as well as a verification section. It can be skipped unless you can ensure all data contained in the message is also represented here.This is an optional component.
  • Extension section: This allows for the definition of any extensions that might be required to support specific clinical workflows e.g. clinical trial applicability. This can be inserted in any of sections to cover specific use cases and workflow needs. This is required if resources include data elements / objects that are not part of the core FHIR models.
  • Contained Resources: Other resources used in identification and transaction processing e.g. message header and the data object corresponding to the type identified earlier such as images etc. that always need to be returned as part of the resource request. This is an optional element.
  • Metadata: Such as version number of the resource. This is an optional element.
  • Resource content: The core content of the resource. In the case of a patient, all relevant details about that patient such as name, address, phone, guardian or other contact info and so on. Each resource has a defined data model. This is a required element (otherwise, why bother?).
  • Tags: Such as security labels which can include ACLs, workflow specific functions, etc. This is optional. It is also under design.

Catalyze FHIR API implementation principles

FHIR is based on API routes. What should the API route look like? The only legitimate link that a quick Google search shows is the Open Epic link. If you haven’t already, I strongly recommend that you sign up here.

Epic has (for now, I’m sure, as they explore the new FHIR world) chosen to define the API structure as below:

https://{domain}/{fhir-version}/api/{resourcesName}/{resourceId}

This is not their intended production route as it does not address potential issues. Perhaps a good way to arrive at what the final API route might look like would be to list out the data needed to be communicated in the API route and the associated impact on the design of the API route itself. Here is the list of possible parameters:

  • The heatlh system / EHR: This is the domain itself. For example, this would translate to {{domain}} viz catalyzehealth.com
  • The environment (prod / dev / …):
  • The FHIR version
  • The partner (or should this be better done via an API key?)
https://{domain}/fhir/{fhir_version}/{environment}/

That will be root or the [base] of all FHIR queries. Additional criteria/parameters will be added on as needed to retrieve the data of interest. For example,

  • The resource
  • The resource ID

In which case, the {resourcesName}/{resourceId} will be tacked on to the end of the root to give us

[base]/{resourcesName}/{resourceId}

General API design principles

Here are a few design principles that we have adopted based on REST best practices.

1. Consistency in naming of routes.

Note that we always use the plural form in the API route. This is just a standard way of denoting it. So all resource names in the route will always be in the plural and the specific ID will always be in the singular i.e.

[base]/{resourcesName}/{resourceId}

and with a specific example for the patient’s resource:

[base]/patients/patientID

2. Consistency in “VERBS” and “NOUNS”

In general, there are three sets of routes or “verbs” per “noun” or resource. They all follow the following pattern:

Actions for POST : /resourcesName/resourceId

This route will allow you to create and get all resources specific to that user. So -

POST /patients

with the associated body will create a patient object. This will also create an internally generated patientId and a createdAt timestamp. Similarly,

POST /patients/6cdf30cc-e81a-4c21-894f-497c5d9ac222/allergies

with the associated body will create an allergy object specific to userID 6cdf30cc-e81a-4c21-894f-497c5d9ac222. This will also create an internally generated allergyId and a createdAt timestamp.

It is important to note that POST actions are unlikely to be supported out of the gate in FHIR implementations but are included here for completeness.

Actions for GET: /resourcesName/resourceId or :/resourcesName?params=value

This route will allow either a specific resource to be returned or, based on the parameters supplied, a list of resources. The only cavaet is likely to be a patient specific query where the parameters will be restricted: i.e. only a specific set of parameters will be allowed to prevent random searches along the lines of give me all patients who’s last name is Smith. We will delve into this in more detail when we look at the patient specific route details in a subsequent section.

GET /allergies/051d8c27-b0c4-432d-a75d-1070fd877206

will return a body with the specific allergy details. In the context of a patient, it is likely that the request being sent must include a minimum set of parameters to return a specific patient rather than a general query as mentioned earlier. So a patient query (GET) will look like this:

GET /patients?lastName=Smith&gender=male&mrn=88776656

which will return a patient resource with associated details as long as there is a specific match. If there is no match, then an empty body will be returned or ideally, would not even trigger a response. This is a potentially useful security precaution to ensure that even null responses do not communicate any information.

Actions for PUT and DELETE: /resourcesName/resourceId

This route will allow you to modify or delete specific resource objects. So -

PUT /allergies/051d8c27-b0c4-432d-a75d-1070fd877206

with the associated body will update the allergy object with ID 051d8c27-b0c4-432d-a75d-1070fd877206

Since allergies always pertain to a unique patient, the same route could be called as

PUT /patients/6cdf30cc-e81a-4c21-894f-497c5d9ac222/allergies/051d8c27-b0c4-432d-a75d-1070fd877206

Similarly for DELETE,

DELETE /allergies/051d8c27-b0c4-432d-a75d-1070fd877206

with an empty body will delete the allergy object with ID 051d8c27-b0c4-432d-a75d-1070fd877206 and the equivalent patient oriented route being

DELETE /patients/6cdf30cc-e81a-4c21-894f-497c5d9ac222/allergies/051d8c27-b0c4-432d-a75d-1070fd877206

Since the allergyId is a unique number, the patientId is overkill but is in there to simplify / rationalize the structure and number of routes you need to remember.

Again, it is important to note that PUT and DELETE actions are unlikely to be supported out of the gate in FHIR implementations but are included in here for completeness.

3. Limiting which fields are returned by the API

You won’t always need the full representation of a resource. The ability select and chose returned fields allows you to minimize network traffic and speed up usage of the API. Therefore, we use a fields query parameter that takes a comma separated list of fields to include. For example,

GET /patients/2f036fb2-80eb-47ee-9d17-b21790f61663?fields=id,name,updatedAt&status=active

would retrieve just enough information to display a sorted listing of allergies for that specific patient (the - sign sorts results in reverse chronological order)

4. APIs are rate limited.

To prevent abuse, it is standard practice to add some sort of rate limiting to an API. RFC 6585 introduced a HTTP status code 429 Too Many Requests to accommodate this. However, it can be very useful to notify you of your limits before you actually hit it.

This is an area that currently lacks standards but has a number of popular conventions using HTTP response headers. At a minimum, include the following headers (using Twitter’s naming conventions because headers typically don’t have mid-word capitalization):

X-Rate-Limit-Limit - The number of allowed requests in the current period
X-Rate-Limit-Remaining - The number of remaining requests in the current period
X-Rate-Limit-Reset - The number of seconds left in the current period

5. Caching - verify on https

HTTP provides a built-in caching framework. All you have to do is include some additional outbound response headers and do a little validation when you receive some inbound request headers. There are 2 approaches: ETag and Last-Modified.

  • ETag: When generating a request, include a HTTP header ETag containing a hash or checksum of the representation. This value should change whenever the output representation changes. Now, if an inbound HTTP request contains a If-None-Match header with a matching ETag value, the API should return a 304 Not Modified status code instead of the output representation of the resource.
  • Last-Modified: This basically works like to ETag, except that it uses timestamps. The response header Last-Modified contains a timestamp in RFC 1123 format which is validated against If-Modified-Since. Note that the HTTP spec has had 3 different acceptable date formats and the server should be prepared to accept any one of them.

6. Errors

Just like an HTML error page shows a useful error message to a visitor, an API should provide a useful error message in a known consumable format. The representation of an error should be no different than the representation of any resource, just with its own set of fields. The API should always return sensible HTTP status codes. API errors typically break down into 2 types:

  • 400 series status codes for client issues &
  • 500 series status codes for server issues.

The API standardize that all 400 series errors come with consumable JSON error representation. If possible (i.e. if load balancers & reverse proxies can create custom error bodies), this should extend to 500 series status codes.

A JSON error body should provide a few things for the developer - a useful error message, a unique error code (that can be looked up for more details in the docs) and possibly a detailed description. JSON output representation for something like this would look like:

    {
      "code" : 1234,
      "message" : "Something bad happened :(",
      "description" : "More details about the error here"
    }

HTTP status codes

HTTP defines a bunch of meaningful status codes that can be returned from your API. These can be leveraged to help the API consumers route their responses accordingly.

  • 200 OK - Response to a successful GET, PUT, PATCH or DELETE. Can also be used for a POST that doesn’t result in a creation.
  • 201 Created - (Not applicable). Response to a POST that results in a creation. Should be combined with a Location header pointing to the location of the new resource
  • 204 No Content - Response to a successful request that won’t be returning a body (like a DELETE request)
  • 304 Not Modified - Used when HTTP caching headers are in play
  • 400 Bad Request - The request is malformed, such as if the body does not parse
  • 401 Unauthorized - When no or invalid authentication details are provided. Also useful to trigger an auth popup if the API is used from a browser
  • 403 Forbidden - When authentication succeeded but authenticated user doesn’t have access to the resource
  • 404 Not Found - When a non-existent resource is requested
  • 405 Method Not Allowed - When an HTTP method is being requested that isn’t allowed for the authenticated user
  • 410 Gone - Indicates that the resource at this end point is no longer available. Useful as a blanket response for old API versions
  • 415 Unsupported Media Type - If incorrect content type was provided as part of the request
  • 422 Unprocessable Entity - Used for validation errors
  • 429 Too Many Requests - When a request is rejected due to rate limiting

7. Result filtering, sorting & searching

It’s best to keep the base resource URLs as lean as possible. Complex result filters, sorting requirements and advanced searching (when restricted to a single type of resource) can all be easily implemented as query parameters on top of the base URL. Let’s look at these in more detail:

  • Filtering: Use a unique query parameter for each field that implements filtering. For example, when requesting a list of allergies from the /allergies endpoint, you may want to limit these to only those in the active state. This could be accomplished with a request like GET /allergies?status=active. Here, status is a query parameter that implements a filter.
  • Sorting: Similar to filtering, a generic parameter sort can be used to describe sorting rules. We accommodate complex sorting requirements by letting the sort parameter take in list of comma separated fields, each with a possible unary negative to imply descending sort order - for example GET /allergies?sort=-severity should retrieve a list of allergies in descending order of severity. Similarly, GET /allergies?sort=-severity,created_at should retrieve a list of allergies in descending order of severity. Within a specific severity, older allergies are ordered first.
  • Searching: When full text search is used as a mechanism of retrieving resource instances for a specific type of resource, it can be exposed on the API as a query parameter on the resource’s endpoint. Let’s say q. Search queries will be passed straight to the search engine and API output will be in the same format as a normal list result.

Combining these together, we can build queries like:

  • Retrieve all users with recently updated allergies: GET /allergies?sort=-updatedAt
  • Retrieve all users with recently updated active allergies: GET /allergies?status=active&sort=-updatedAt
  • Retrieve the set of users with highest severity active allergies mentioning the word ‘pollen’: GET /allergies?q=pollen&status=active&sort=-severity,createdAt

8. Using Contained Resources (Expansion)

You can use expansion to retrieve particular details about resources in the same response you get when you request a list of users, for instance, in a search. This is a perfect example of a contained resource. By using expansion, you avoid the process of retrieving the list and then making additional calls to retrieve details about each item in the list. This is more efficient and helps you avoid running up against the limits of your quota.

Patients play a central role in many of the responses returned by resources. For example, queries such as allergy searches, medications all return patient-centric responses. You can expand the patient response format so you can access details about each patient without having to make additional patient resource queries on the individual patients in the response. For example, you can query for patients that match some criteria and at the same time ask the Catalyze API to extend its response format so that it includes additional details about each patient other than those in the default response format.

Summary

These are the general design principles that we have followed at Catalyze. These are guidelines based on our experience building RESTful APIs and gathered from multiple other sources. The key underlying principles being consistency and adherence with HTTP standards.

Patient Resource

The FHIR Patient resource defines demographics, care providers, and other administrative information about a person receiving care at a health organization. The FHIR spec details out the entire set of fields that a patient resource can return. A full listing of all the fields is available here. It is also listed in the table below for convenience. (Note that all animal related terms have been eliminated from this list below).

Data Element Description
Patient.identifier An identifier that applies to this person as a patient.
Patient.name A name associated with the individual. Person may have multiple names with different uses or applicable periods.For animals, the name is a “HumanName” in the sense that is assigned and used by humans and has the same patterns.
Patient.telecom A contact detail (e.g. a telephone number or an email address) by which the individual may be contacted. Person may have multiple ways to be contacted with different uses or applicable periods. May need to have options for contacting the person urgently and also to help with identification. The address may not go directly to the individual, but may reach another party that is able to proxy for the patient (i.e. home phone, or pet owner’s phone).
Patient.gender Administrative Gender - the gender that the patient is considered to have for administration and record keeping purposes. Needed for identification of the individual, in combination with (at least) name and birth date. Gender of individual drives many clinical processes.
Patient.birthDate The date and time of birth for the individual. At least an estimated year should be provided as a guess if the real dob is unknown.
Patient.deceased Indicates if the individual is deceased or not.
Patient.address Addresses for the individual. May need to keep track of persons addresses for contacting, billing or reporting requirements and also to help with identification.
Patient.maritalStatus This field contains a patient’s most recent marital (civil) status. See this link for a listing of allowed code values
Patient.multipleBirth[x] Indicates whether the patient is part of a multiple or indicates the actual birth order.
Patient.photo Image of the person. Many EHR systems have the capability to capture an image of the patient. Fits with newer social media usage too.
Patient.contact A contact party (e.g. guardian, partner, friend) for the patient. Contact covers all kinds of contact parties: family members, business contacts, guardians, caregivers. Not applicable to register pedigree and family ties beyond use of having contact.
Patient.contact.relationship The nature of the relationship between the patient and the contact person. See this link for a listing of allowed code values
Patient.contact.name A name associated with the person. Contact persons need to be identified by name, but it is uncommon to need details about multiple other names for that person.
Patient.contact.telecom A contact detail for the person, e.g. a telephone number or an email address.
Patient.contact.address Address for the contact person.
Patient.contact.gender Administrative Gender - the gender that the person is considered to have for administration and record keeping purposes. See this link for a listing of allowed code values
Patient.contact.organization Organization on behalf of which the contact is acting or for which the contact is working. For guardians or business related contacts, the organization is relevant.
Patient.communication Languages which may be used to communicate with the patient about his or her health. See IETF language tag
Patient.careProvider Patient’s nominated care provider. Resource(Organization
Patient.managingOrganization Organization that is the custodian of the patient record.
Patient.link Link to another patient resource that concerns the same actual person. There are multiple usecases: * Duplicate patient records due to the clerical errors associated with the difficulties of identifying humans consistently, and * Distribution of patient information across multiple servers.
Patient.link.other The other patient resource that the link refers to.
Patient.link.type The type of link between this patient resource and another patient resource. See this link for a listing of allowed code values
Patient.active Need to be able to mark a patient record as not to be used because it was created in error.If a record is inactive, and linked to an active record, then future patient/person/record updates should occur on the other patient.

Patient FHIR API routes

We think it is worthwhile to call the patient route out as most FHIR queries are likely to be patient oriented and then combined with other resources such as medications, allergies etc. Note that usually the patient ID (or any ID for matter) is likely to be a GUID. This route will allow you to ask questions like Give me a list of all patients who fit a particular set of criteria. So -

GET /patients?params=value
Show the result of GET /patients?email=r.garcia@white.com

Possible / allowed parameters

Acceptable values of parameters will be dependent on the specific information and should be accessible via the conformance request. However, a minimal set that can be expected to be supported are shown in the table below. These are also supported in the Catalyze FHIR API. Again note that all animal related paths have been eliminated here.

Name Description Paths
id The logical resource id associated with the resource (must be supported by all servers)
identifier A patient identifier such as MRN, DL, SSN etc. Patient.identifier
address Full or part of an address in any kind of address specified as part of the patient record Patient.address
birthdate The patient’s date of birth Patient.birthDate
family A portion of the family name of the patient Patient.name.family
gender Gender of the patient Patient.gender
given A portion of the given name of the patient Patient.name.given
name A portion of either family or given name of the patient Patient.name
provider The organization at which this person is a patient Patient.managingOrganization (Organization)
telecom The value in any kind of telecom details of the patient Patient.telecom

Examples

This is where the flow will generally start. You make a query to get the information about a specific patient.

Query Results Try it!
GET /patients?name=Smith List of patients with last name of Smith. Clicking the Toggle button will return the list of patients with the last of “Smith” in the sample test data we have.
GET /patients?name=Smith&gender=F Females with the last name of Smith. Click on the Toggle button to return that subset
GET /patients/22283003-8c26-4b24-bbe9-b38756908eb5 Patient with that specific identifier. This usually assumes that the lookup has happened by patient already and a specific ID of the patient has been retrieved.
GET /patients?name=Smith
{ 
  "patients" : [ 
    { 
      "resourceType" : "Patient",
      "id" : "22283003-8c26-4b24-bbe9-b38756908eb5",
      "identifier" : [ 
        { 
          "use" : "official",
          "label" : "SSN",
          "value" : "3472302",
          "system" : "urn:oid:1.2.36.146.595.217.0.1",
          "period" : { 
            "start" : "1995-02-22"
            },
          "assigner" : { 
            "display" : "Veniam Healthcare"
            }
          }
        ],
      "name" : [ 
        { 
          "use" : "usual",
          "family" : [ 
            "Smith"
            ],
          "given" : [ 
            "Mary"
            ]
          }
        ],
      "telecom" : [ 
        { 
          "system" : "phone",
          "value" : "010-259-1505",
          "use" : "mobile"
          },
        { 
          "system" : "phone",
          "value" : "863-617-8031",
          "use" : "work"
          }
        ],
      "gender" : { 
        "coding" : [ 
          { 
            "system" : "http://snomed.info/sct",
            "code" : "248153007",
            "display" : "Female"
            }
          ]
        },
      "birthDate" : "2008-08-07",
      "deceasedBoolean" : false,
      "address" : [ 
        { 
          "use" : "home",
          "line" : "222  Ipsum , Apt 336",
          "city" : "Wilson",
          "state" : "California",
          "zip" : "81646"
          }
        ],
      "maritalStatus" : { 
        "coding" : [ 
          { 
            "system" : "http://snomed.info/sct",
            "code" : "36629006",
            "display" : "Legally married"
            }
          ]
        },
      "contact" : [ 
        { 
          "relationship" : [ 
            { 
              "coding" : [ 
                { 
                  "system" : "http://hl7.org/fhir/patient-contact-relationship",
                  "code" : "partner"
                  }
                ]
              }
            ],
          "name" : { 
            "family" : [ 
              "Smith",
              "Davis"
              ],
            "_family" : [ 
              { 
                "extension" : [ 
                  { 
                    "url" : "http://hl7.org/fhir/Profile/iso-21090#qualifier",
                    "valueCode" : "VV"
                    }
                  ]
                }
              ],
            "given" : [ 
              "Jennifer"
              ]
            },
          "telecom" : [ 
            { 
              "system" : "phone",
              "value" : "301-773-9840",
              "use" : "work"
              },
            { 
              "system" : "phone",
              "value" : "331-366-9964",
              "use" : "mobile"
              }
            ]
          }
        ],
      "managingOrganization" : { 
        "reference" : "organization/7448b2c0-c954-4cd4-9de8-0fdd4ce43256"
        },
      "active" : true
      },
    { 
      "resourceType" : "Patient",
      "id" : "0aedd6e8-0649-4a02-a80d-f89b1c405079",
      "identifier" : [ 
        { 
          "use" : "usual",
          "label" : "SSN",
          "value" : "4317289",
          "system" : "urn:oid:1.2.36.146.595.217.0.1",
          "period" : { 
            "start" : "1994-05-25"
            },
          "assigner" : { 
            "display" : "Dolore Healthcare"
            }
          },
        { 
          "use" : "official",
          "label" : "DL",
          "value" : "1216422",
          "system" : "urn:oid:1.2.36.146.595.217.0.1",
          "period" : { 
            "start" : "1984-11-05"
            },
          "assigner" : { 
            "display" : "Cupidatat Healthcare"
            }
          },
        { 
          "use" : "usual",
          "label" : "MRN",
          "value" : "0729603",
          "system" : "urn:oid:1.2.36.146.595.217.0.1",
          "period" : { 
            "start" : "1999-08-17"
            },
          "assigner" : { 
            "display" : "Aliqua Healthcare"
            }
          }
        ],
      "name" : [ 
        { 
          "use" : "usual",
          "family" : [ 
            "Smith"
            ],
          "given" : [ 
            "Charles"
            ]
          }
        ],
      "telecom" : [ 
        { 
          "system" : "phone",
          "value" : "653-220-7687",
          "use" : "mobile"
          },
        { 
          "system" : "phone",
          "value" : "161-512-9337",
          "use" : "work"
          }
        ],
      "gender" : { 
        "coding" : [ 
          { 
            "system" : "http://snomed.info/sct",
            "code" : "248153007",
            "display" : "Male"
            }
          ]
        },
      "birthDate" : "2014-03-28",
      "deceasedBoolean" : false,
      "address" : [ 
        { 
          "use" : "work",
          "line" : "128  Occaecat , Apt 518",
          "city" : "Johnson",
          "state" : "Wisconsin",
          "zip" : "25028"
          },
        { 
          "use" : "work",
          "line" : "348  Culpa , Apt 364",
          "city" : "Robinson",
          "state" : "California",
          "zip" : "42768"
          }
        ],
      "maritalStatus" : { 
        "coding" : [ 
          { 
            "system" : "http://snomed.info/sct",
            "code" : "36629006",
            "display" : "Legally married"
            }
          ]
        },
      "contact" : [ 
        { 
          "relationship" : [ 
            { 
              "coding" : [ 
                { 
                  "system" : "http://hl7.org/fhir/patient-contact-relationship",
                  "code" : "partner"
                  }
                ]
              }
            ],
          "name" : { 
            "family" : [ 
              "Walker",
              "White"
              ],
            "_family" : [ 
              { 
                "extension" : [ 
                  { 
                    "url" : "http://hl7.org/fhir/Profile/iso-21090#qualifier",
                    "valueCode" : "VV"
                    }
                  ]
                }
              ],
            "given" : [ 
              "Helen",
              "Cynthia"
              ]
            },
          "telecom" : [ 
            { 
              "system" : "phone",
              "value" : "690-198-4895",
              "use" : "home"
              }
            ]
          }
        ],
      "managingOrganization" : { 
        "reference" : "organization/ce7509ca-bdc3-4198-b802-99845fd6d06d"
        },
      "active" : true
      },
    { 
      "resourceType" : "Patient",
      "id" : "8cc95829-996a-4f3e-9a6f-f9e65cae96ed",
      "identifier" : [ 
        { 
          "use" : "usual",
          "label" : "MRN",
          "value" : "8377334",
          "system" : "urn:oid:1.2.36.146.595.217.0.1",
          "period" : { 
            "start" : "1990-08-11"
            },
          "assigner" : { 
            "display" : "Pariatur Healthcare"
            }
          },
        { 
          "use" : "usual",
          "label" : "MRN",
          "value" : "3333631",
          "system" : "urn:oid:1.2.36.146.595.217.0.1",
          "period" : { 
            "start" : "1995-04-10"
            },
          "assigner" : { 
            "display" : "Laborum Healthcare"
            }
          }
        ],
      "name" : [ 
        { 
          "use" : "official",
          "family" : [ 
            "Smith"
            ],
          "given" : [ 
            "Christopher",
            "Paul"
            ]
          }
        ],
      "telecom" : [ 
        { 
          "system" : "phone",
          "value" : "823-418-1646",
          "use" : "mobile"
          },
        { 
          "system" : "phone",
          "value" : "284-423-4317",
          "use" : "work"
          }
        ],
      "gender" : { 
        "coding" : [ 
          { 
            "system" : "http://snomed.info/sct",
            "code" : "248153007",
            "display" : "Male"
            },
          { 
            "system" : "http://snomed.info/sct",
            "code" : "248153007",
            "display" : "Male"
            }
          ]
        },
      "birthDate" : "2001-10-25",
      "deceasedBoolean" : false,
      "address" : [ 
        { 
          "use" : "home",
          "line" : "349  Veniam , Apt 831",
          "city" : "Martinez",
          "state" : "California",
          "zip" : "07296"
          },
        { 
          "use" : "work",
          "line" : "234  Velit , Apt 306",
          "city" : "Hernandez",
          "state" : "Texas",
          "zip" : "24418"
          }
        ],
      "maritalStatus" : { 
        "coding" : [ 
          { 
            "system" : "http://snomed.info/sct",
            "code" : "36629006",
            "display" : "Legally married"
            }
          ]
        },
      "contact" : [ 
        { 
          "relationship" : [ 
            { 
              "coding" : [ 
                { 
                  "system" : "http://hl7.org/fhir/patient-contact-relationship",
                  "code" : "partner"
                  }
                ]
              }
            ],
          "name" : { 
            "family" : [ 
              "Williams"
              ],
            "_family" : [ 
              { 
                "extension" : [ 
                  { 
                    "url" : "http://hl7.org/fhir/Profile/iso-21090#qualifier",
                    "valueCode" : "VV"
                    }
                  ]
                }
              ],
            "given" : [ 
              "Maria",
              "Betty"
              ]
            },
          "telecom" : [ 
            { 
              "system" : "phone",
              "value" : "224-979-9654",
              "use" : "mobile"
              },
            { 
              "system" : "phone",
              "value" : "513-740-2880",
              "use" : "mobile"
              }
            ]
          }
        ],
      "managingOrganization" : { 
        "reference" : "organization/7448b2c0-c954-4cd4-9de8-0fdd4ce43256"
        },
      "active" : true
      },
    { 
      "resourceType" : "Patient",
      "id" : "d4033832-ff62-4dd2-9465-e09a73f9683f",
      "identifier" : [ 
        { 
          "use" : "usual",
          "label" : "SSN",
          "value" : "4816086",
          "system" : "urn:oid:1.2.36.146.595.217.0.1",
          "period" : { 
            "start" : "2010-07-16"
            },
          "assigner" : { 
            "display" : "Lorem Healthcare"
            }
          },
        { 
          "use" : "usual",
          "label" : "DL",
          "value" : "1022938",
          "system" : "urn:oid:1.2.36.146.595.217.0.1",
          "period" : { 
            "start" : "1981-12-21"
            },
          "assigner" : { 
            "display" : "Non Healthcare"
            }
          }
        ],
      "name" : [ 
        { 
          "use" : "official",
          "family" : [ 
            "Smith"
            ],
          "given" : [ 
            "Donald",
            "Jose"
            ]
          }
        ],
      "telecom" : [ 
        { 
          "system" : "phone",
          "value" : "690-198-4895",
          "use" : "home"
          }
        ],
      "gender" : { 
        "coding" : [ 
          { 
            "system" : "http://snomed.info/sct",
            "code" : "248153007",
            "display" : "Male"
            }
          ]
        },
      "birthDate" : "1982-09-16",
      "deceasedBoolean" : false,
      "address" : [ 
        { 
          "use" : "home",
          "line" : "961  Consectetur , Apt 743",
          "city" : "Smith",
          "state" : "California",
          "zip" : "33336"
          },
        { 
          "use" : "work",
          "line" : "204  Eiusmod , Apt 979",
          "city" : "Wilson",
          "state" : "New York",
          "zip" : "98405"
          }
        ],
      "maritalStatus" : { 
        "coding" : [ 
          { 
            "system" : "http://snomed.info/sct",
            "code" : "36629006",
            "display" : "Legally married"
            }
          ]
        },
      "contact" : [ 
        { 
          "relationship" : [ 
            { 
              "coding" : [ 
                { 
                  "system" : "http://hl7.org/fhir/patient-contact-relationship",
                  "code" : "partner"
                  }
                ]
              }
            ],
          "name" : { 
            "family" : [ 
              "Thomas",
              "Robinson"
              ],
            "_family" : [ 
              { 
                "extension" : [ 
                  { 
                    "url" : "http://hl7.org/fhir/Profile/iso-21090#qualifier",
                    "valueCode" : "VV"
                    }
                  ]
                }
              ],
            "given" : [ 
              "Nancy"
              ]
            },
          "telecom" : [ 
            { 
              "system" : "phone",
              "value" : "602-652-9487",
              "use" : "mobile"
              },
            { 
              "system" : "phone",
              "value" : "895-612-1797",
              "use" : "work"
              }
            ]
          }
        ],
      "managingOrganization" : { 
        "reference" : "organization/2a6fbe28-a851-44cb-b54e-77c1eadc2475"
        },
      "active" : true
      },
    { 
      "resourceType" : "Patient",
      "id" : "0aedd6e8-0649-4a02-a80d-f89b1c405079",
      "identifier" : [ 
        { 
          "use" : "usual",
          "label" : "SSN",
          "value" : "5805269",
          "system" : "urn:oid:1.2.36.146.595.217.0.1",
          "period" : { 
            "start" : "1980-11-06"
            },
          "assigner" : { 
            "display" : "Ullamco Healthcare"
            }
          },
        { 
          "use" : "usual",
          "label" : "DL",
          "value" : "2176891",
          "system" : "urn:oid:1.2.36.146.595.217.0.1",
          "period" : { 
            "start" : "1980-03-04"
            },
          "assigner" : { 
            "display" : "Incididunt Healthcare"
            }
          }
        ],
      "name" : [ 
        { 
          "use" : "official",
          "family" : [ 
            "Smith"
            ],
          "given" : [ 
            "Laurelai",
            "Rory"
            ]
          }
        ],
      "telecom" : [ 
        { 
          "system" : "phone",
          "value" : "224-979-9654",
          "use" : "mobile"
          },
        { 
          "system" : "phone",
          "value" : "513-740-2880",
          "use" : "mobile"
          }
        ],
      "gender" : { 
        "coding" : [ 
          { 
            "system" : "http://snomed.info/sct",
            "code" : "248153007",
            "display" : "Female"
            }
          ]
        },
      "birthDate" : "1995-02-22",
      "deceasedBoolean" : false,
      "address" : [ 
        { 
          "use" : "work",
          "line" : "364  Cupidatat , Apt 012",
          "city" : "Jones",
          "state" : "Pennsylvania",
          "zip" : "10229"
          }
        ],
      "maritalStatus" : { 
        "coding" : [ 
          { 
            "system" : "http://snomed.info/sct",
            "code" : "36629006",
            "display" : "Legally married"
            }
          ]
        },
      "contact" : [ 
        { 
          "relationship" : [ 
            { 
              "coding" : [ 
                { 
                  "system" : "http://hl7.org/fhir/patient-contact-relationship",
                  "code" : "partner"
                  }
                ]
              }
            ],
          "name" : { 
            "family" : [ 
              "Allen",
              "Martin"
              ],
            "_family" : [ 
              { 
                "extension" : [ 
                  { 
                    "url" : "http://hl7.org/fhir/Profile/iso-21090#qualifier",
                    "valueCode" : "VV"
                    }
                  ]
                }
              ],
            "given" : [ 
              "Jason",
              "Robert"
              ]
            },
          "telecom" : [ 
            { 
              "system" : "phone",
              "value" : "448-222-3122",
              "use" : "work"
              }
            ]
          }
        ],
      "managingOrganization" : { 
        "reference" : "organization/2a6fbe28-a851-44cb-b54e-77c1eadc2475"
        },
      "active" : true
      }
    ]
  }
GET /patients?name=Smith&gender=F
{ 
  "patients" : [ 
    { 
      "resourceType" : "Patient",
      "id" : "22283003-8c26-4b24-bbe9-b38756908eb5",
      "identifier" : [ 
        { 
          "use" : "official",
          "label" : "SSN",
          "value" : "3472302",
          "system" : "urn:oid:1.2.36.146.595.217.0.1",
          "period" : { 
            "start" : "1995-02-22"
            },
          "assigner" : { 
            "display" : "Veniam Healthcare"
            }
          }
        ],
      "name" : [ 
        { 
          "use" : "usual",
          "family" : [ 
            "Smith"
            ],
          "given" : [ 
            "Mary"
            ]
          }
        ],
      "telecom" : [ 
        { 
          "system" : "phone",
          "value" : "010-259-1505",
          "use" : "mobile"
          },
        { 
          "system" : "phone",
          "value" : "863-617-8031",
          "use" : "work"
          }
        ],
      "gender" : { 
        "coding" : [ 
          { 
            "system" : "http://snomed.info/sct",
            "code" : "248153007",
            "display" : "Female"
            }
          ]
        },
      "birthDate" : "2008-08-07",
      "deceasedBoolean" : false,
      "address" : [ 
        { 
          "use" : "home",
          "line" : "222  Ipsum , Apt 336",
          "city" : "Wilson",
          "state" : "California",
          "zip" : "81646"
          }
        ],
      "maritalStatus" : { 
        "coding" : [ 
          { 
            "system" : "http://snomed.info/sct",
            "code" : "36629006",
            "display" : "Legally married"
            }
          ]
        },
      "contact" : [ 
        { 
          "relationship" : [ 
            { 
              "coding" : [ 
                { 
                  "system" : "http://hl7.org/fhir/patient-contact-relationship",
                  "code" : "partner"
                  }
                ]
              }
            ],
          "name" : { 
            "family" : [ 
              "Smith",
              "Davis"
              ],
            "_family" : [ 
              { 
                "extension" : [ 
                  { 
                    "url" : "http://hl7.org/fhir/Profile/iso-21090#qualifier",
                    "valueCode" : "VV"
                    }
                  ]
                }
              ],
            "given" : [ 
              "Jennifer"
              ]
            },
          "telecom" : [ 
            { 
              "system" : "phone",
              "value" : "301-773-9840",
              "use" : "work"
              },
            { 
              "system" : "phone",
              "value" : "331-366-9964",
              "use" : "mobile"
              }
            ]
          }
        ],
      "managingOrganization" : { 
        "reference" : "organization/7448b2c0-c954-4cd4-9de8-0fdd4ce43256"
        },
      "active" : true
      },
    { 
      "resourceType" : "Patient",
      "id" : "0aedd6e8-0649-4a02-a80d-f89b1c405079",
      "identifier" : [ 
        { 
          "use" : "usual",
          "label" : "SSN",
          "value" : "5805269",
          "system" : "urn:oid:1.2.36.146.595.217.0.1",
          "period" : { 
            "start" : "1980-11-06"
            },
          "assigner" : { 
            "display" : "Ullamco Healthcare"
            }
          },
        { 
          "use" : "usual",
          "label" : "DL",
          "value" : "2176891",
          "system" : "urn:oid:1.2.36.146.595.217.0.1",
          "period" : { 
            "start" : "1980-03-04"
            },
          "assigner" : { 
            "display" : "Incididunt Healthcare"
            }
          }
        ],
      "name" : [ 
        { 
          "use" : "official",
          "family" : [ 
            "Smith"
            ],
          "given" : [ 
            "Laurelai",
            "Rory"
            ]
          }
        ],
      "telecom" : [ 
        { 
          "system" : "phone",
          "value" : "224-979-9654",
          "use" : "mobile"
          },
        { 
          "system" : "phone",
          "value" : "513-740-2880",
          "use" : "mobile"
          }
        ],
      "gender" : { 
        "coding" : [ 
          { 
            "system" : "http://snomed.info/sct",
            "code" : "248153007",
            "display" : "Female"
            }
          ]
        },
      "birthDate" : "1995-02-22",
      "deceasedBoolean" : false,
      "address" : [ 
        { 
          "use" : "work",
          "line" : "364  Cupidatat , Apt 012",
          "city" : "Jones",
          "state" : "Pennsylvania",
          "zip" : "10229"
          }
        ],
      "maritalStatus" : { 
        "coding" : [ 
          { 
            "system" : "http://snomed.info/sct",
            "code" : "36629006",
            "display" : "Legally married"
            }
          ]
        },
      "contact" : [ 
        { 
          "relationship" : [ 
            { 
              "coding" : [ 
                { 
                  "system" : "http://hl7.org/fhir/patient-contact-relationship",
                  "code" : "partner"
                  }
                ]
              }
            ],
          "name" : { 
            "family" : [ 
              "Allen",
              "Martin"
              ],
            "_family" : [ 
              { 
                "extension" : [ 
                  { 
                    "url" : "http://hl7.org/fhir/Profile/iso-21090#qualifier",
                    "valueCode" : "VV"
                    }
                  ]
                }
              ],
            "given" : [ 
              "Jason",
              "Robert"
              ]
            },
          "telecom" : [ 
            { 
              "system" : "phone",
              "value" : "448-222-3122",
              "use" : "work"
              }
            ]
          }
        ],
      "managingOrganization" : { 
        "reference" : "organization/2a6fbe28-a851-44cb-b54e-77c1eadc2475"
        },
      "active" : true
      }
    ]
  }
GET /patients/22283003-8c26-4b24-bbe9-b38756908eb5
{ 
  "patients" : [ 
    { 
      "resourceType" : "Patient",
      "id" : "22283003-8c26-4b24-bbe9-b38756908eb5",
      "identifier" : [ 
        { 
          "use" : "official",
          "label" : "SSN",
          "value" : "3472302",
          "system" : "urn:oid:1.2.36.146.595.217.0.1",
          "period" : { 
            "start" : "1995-02-22"
            },
          "assigner" : { 
            "display" : "Veniam Healthcare"
            }
          }
        ],
      "name" : [ 
        { 
          "use" : "usual",
          "family" : [ 
            "Smith"
            ],
          "given" : [ 
            "Mary"
            ]
          }
        ],
      "telecom" : [ 
        { 
          "system" : "phone",
          "value" : "010-259-1505",
          "use" : "mobile"
          },
        { 
          "system" : "phone",
          "value" : "863-617-8031",
          "use" : "work"
          }
        ],
      "gender" : { 
        "coding" : [ 
          { 
            "system" : "http://snomed.info/sct",
            "code" : "248153007",
            "display" : "Female"
            }
          ]
        },
      "birthDate" : "2008-08-07",
      "deceasedBoolean" : false,
      "address" : [ 
        { 
          "use" : "home",
          "line" : "222  Ipsum , Apt 336",
          "city" : "Wilson",
          "state" : "California",
          "zip" : "81646"
          }
        ],
      "maritalStatus" : { 
        "coding" : [ 
          { 
            "system" : "http://snomed.info/sct",
            "code" : "36629006",
            "display" : "Legally married"
            }
          ]
        },
      "contact" : [ 
        { 
          "relationship" : [ 
            { 
              "coding" : [ 
                { 
                  "system" : "http://hl7.org/fhir/patient-contact-relationship",
                  "code" : "partner"
                  }
                ]
              }
            ],
          "name" : { 
            "family" : [ 
              "Smith",
              "Davis"
              ],
            "_family" : [ 
              { 
                "extension" : [ 
                  { 
                    "url" : "http://hl7.org/fhir/Profile/iso-21090#qualifier",
                    "valueCode" : "VV"
                    }
                  ]
                }
              ],
            "given" : [ 
              "Jennifer"
              ]
            },
          "telecom" : [ 
            { 
              "system" : "phone",
              "value" : "301-773-9840",
              "use" : "work"
              },
            { 
              "system" : "phone",
              "value" : "331-366-9964",
              "use" : "mobile"
              }
            ]
          }
        ],
      "managingOrganization" : { 
        "reference" : "organization/7448b2c0-c954-4cd4-9de8-0fdd4ce43256"
        },
      "active" : true
      }
    ]
  }

Obviously this set of patients is restricted to your app and whether the requesting application has the appropriate permissions to view this data. This could get tricky and the initial approach taken by a lot of the implementations by EHR vendors enable only a subset of search capabilities and seem to be tied to the patient identifier. The patient search parameters will also likely be restricted. Note that you can use the API above directly in your development. Just use it as you would any API request / response. We haven’t gated this with an API key as this is just randomly generated data. The structure of the JSON does adhere to the FHIR standard of course.

Organization and Practitioner, Provider Resources

These fall under the bucket of administrative resources. So does the Patient resource but we’ve pulled that out into its own section given that it is core to every clinical request.

Organization Resource

An organization is defined by FHIR as “a formally or informally recognized grouping of people or organizations formed for the purpose of achieving some form of collective action”. The organization’s resource definition includes companies, institutions, corporations, departments, community groups, healthcare practice groups, etc. A full listing of all the fields is available here.

The general route should be as follows:

GET /organizations?params=value

Possible / allowed parameters

Acceptable values of parameters will be dependent on the specific information and should be accessible via the conformance request. However, a minimal set that can be expected to be supported are shown in the table below. The only parameter currently supported in the Catalyze FHIR api are the id, identifier and name parameters.

Name Description Paths
id The logical resource id associated with the resource (must be supported by all servers)
active Whether the organization’s record is active Organization.active
identifier Any identifier for the organization (not the accreditation issuer’s identifier) Organization.identifier
name A portion of the organization’s name Organization.name
partof Search all organizations that are part of the given organization Organization.partOf (Organization)
type A code for the type of organization. See here for a listing Organization.type

Examples

Query Results Try it!
GET /organizations/ce7509ca-bdc3-4198-b802-99845fd6d06d Retrieve a specific organization by its ID. In the general context and for most use cases, the developer should have this ID already available. The only context in which the ID might not be available is in the context of an HIE and a query that needs to pull in information about a specific patient from across multiple organizations. This, of course, has significant security and access control challenges. So we’ll leave that out for the time being.
GET /organizations?identifier=A3032873 This identifier could be anything such as NPI number, DEA number, D&B etc. Note that these must be organization level identifiers. Provider level identifiers will, of course, not work in this context.
GET /organizations?name="LOREM HEALTHCARE" The name parameter is enabled in this Catalyze implementation but in a real life deployment there can be multitude of matches to a name. Which also implies possibly a central authority with identifiers of all organizations.
GET /organizations/ce7509ca-bdc3-4198-b802-99845fd6d06d
  { 
      "resourceType" : "Organization",
      "id" : "ce7509ca-bdc3-4198-b802-99845fd6d06d",
      "identifier" : [ 
        { 
          "use" : "official",
          "system" : "urn:oid:2.16.528.1",
          "value" : "1386378"
          }
        ],
      "name" : "Aliqua Healthcare",
      "type" : { 
        "coding" : [ 
          { 
            "system" : "urn:oid:2.16.840.1.113883.2.4.15.1060",
            "code" : "V6",
            "display" : "University Medical Hospital"
            },
          { 
            "system" : "urn:oid:2.16.840.1.113883.2.4.15.1060",
            "code" : "V6",
            "display" : "University Medical Hospital"
            }
          ]
        },
      "telecom" : [ 
        { 
          "system" : "phone",
          "value" : "824-021-3762",
          "use" : "work"
          }
        ],
      "address" : [ 
        { 
          "use" : "work",
          "line" : [ 
            "220  Sit , # 801"
            ],
          "city" : "Miller",
          "zip" : "12434"
          },
        { 
          "use" : "work",
          "line" : [ 
            "399  Sint , # 224"
            ],
          "city" : "Allen",
          "zip" : "96542"
          }
        ],
      "contact" : [ 
        { 
          "purpose" : { 
            "coding" : [ 
              { 
                "system" : "http://hl7.org/fhir/contactentity-type",
                "code" : "PRESS"
                },
              { 
                "system" : "http://hl7.org/fhir/contactentity-type",
                "code" : "PATINF"
                }
              ]
            },
          "telecom" : [ 
            { 
              "system" : "phone",
              "value" : "518-034-6250"
              }
            ]
          },
        { 
          "purpose" : { 
            "coding" : [ 
              { 
                "system" : "http://hl7.org/fhir/contactentity-type",
                "code" : "PRESS"
                }
              ]
            },
          "telecom" : [ 
            { 
              "system" : "phone",
              "value" : "899-364-3207"
              }
            ]
          }
        ]
      }
GET /organizations?identifier=A3032873
    { 
      "organization" : [ 
        { 
          "resourceType" : "Organization",
          "id" : "1bbf798f-e2a4-4539-bede-63f38f02d8a4",
          "identifier" : [ 
            { 
              "use" : "official",
              "system" : "urn:oid:2.16.528.1",
              "value" : "A3032873"
              }
            ],
          "name" : "Voluptate Healthcare",
          "type" : { 
            "coding" : [ 
              { 
                "system" : "urn:oid:2.16.840.1.113883.2.4.15.1060",
                "code" : "V6",
                "display" : "University Medical Hospital"
                },
              { 
                "system" : "urn:oid:2.16.840.1.113883.2.4.15.1060",
                "code" : "V6",
                "display" : "University Medical Hospital"
                }
              ]
            },
          "telecom" : [ 
            { 
              "system" : "phone",
              "value" : "613-306-4935",
              "use" : "work"
              }
            ],
          "address" : [ 
            { 
              "use" : "work",
              "line" : [ 
                "021  Incididunt , Apt 907"
                ],
              "city" : "Lopez",
              "zip" : "20496"
              }
            ],
          "contact" : [ 
            { 
              "purpose" : { 
                "coding" : [ 
                  { 
                    "system" : "http://hl7.org/fhir/contactentity-type",
                    "code" : "PATINF"
                    },
                  { 
                    "system" : "http://hl7.org/fhir/contactentity-type",
                    "code" : "PRESS"
                    }
                  ]
                },
              "telecom" : [ 
                { 
                  "system" : "phone",
                  "value" : "399-801-2474"
                  }
                ]
              },
            { 
              "purpose" : { 
                "coding" : [ 
                  { 
                    "system" : "http://hl7.org/fhir/contactentity-type",
                    "code" : "PRESS"
                    },
                  { 
                    "system" : "http://hl7.org/fhir/contactentity-type",
                    "code" : "PRESS"
                    }
                  ]
                },
              "telecom" : [ 
                { 
                  "system" : "phone",
                  "value" : "740-128-1866"
                  }
                ]
              }
            ]
          }
        ]
      }
GET /organizations?name=“LOREM HEALTHCARE”
    { 
      "organization" : [ 
        { 
          "resourceType" : "Organization",
          "id" : "ce7509ca-bdc3-4198-b802-99845fd6d06d",
          "identifier" : [ 
            { 
              "use" : "official",
              "system" : "urn:oid:2.16.528.1",
              "value" : "2502838"
              },
            { 
              "use" : "official",
              "system" : "urn:oid:2.16.528.1",
              "value" : "6369630"
              }
            ],
          "name" : "Lorem Healthcare",
          "type" : { 
            "coding" : [ 
              { 
                "system" : "urn:oid:2.16.840.1.113883.2.4.15.1060",
                "code" : "V6",
                "display" : "University Medical Hospital"
                },
              { 
                "system" : "urn:oid:2.16.840.1.113883.2.4.15.1060",
                "code" : "V6",
                "display" : "University Medical Hospital"
                }
              ]
            },
          "telecom" : [ 
            { 
              "system" : "phone",
              "value" : "832-012-4276",
              "use" : "work"
              }
            ],
          "address" : [ 
            { 
              "use" : "work",
              "line" : [ 
                "259  Velit , Apt 713"
                ],
              "city" : "Walker",
              "zip" : "17848"
              },
            { 
              "use" : "work",
              "line" : [ 
                "500  Esse , Apt 440"
                ],
              "city" : "Walker",
              "zip" : "87249"
              }
            ],
          "contact" : [ 
            { 
              "purpose" : { 
                "coding" : [ 
                  { 
                    "system" : "http://hl7.org/fhir/contactentity-type",
                    "code" : "PATINF"
                    }
                  ]
                },
              "telecom" : [ 
                { 
                  "system" : "phone",
                  "value" : "031-336-8155"
                  }
                ]
              },
            { 
              "purpose" : { 
                "coding" : [ 
                  { 
                    "system" : "http://hl7.org/fhir/contactentity-type",
                    "code" : "PATINF"
                    }
                  ]
                },
              "telecom" : [ 
                { 
                  "system" : "phone",
                  "value" : "459-961-1263"
                  }
                ]
              }
            ]
          }
        ]
      }

Practitioner’s Resource

The FHIR definition of Practitioner covers all individuals who are engaged in the healthcare process and healthcare-related services as part of their formal responsibilities and this Resource is used for attribution of activities and responsibilities to these individuals. Practitioners include (but are not limited to): physicians, dentists, pharmacists, physician assistants, nurses and scribes. We are not necessarily fans of the name of the resource, so expect to see lots of misspellings and confusion. We should perhaps have stuck with the term “providers” rather than “practitioners”.

A full listing of all the fields that are included in the resource definition is available here.

The general route should be as follows:

GET /practitioners?params=value

Possible / allowed parameters

Acceptable values of parameters will be dependent on the specific information and should be accessible via the conformance request. However, a minimal set that can be expected to be supported are shown in the table below. The only parameter currently supported in the Catalyze FHIR api are the id, identifier and name parameters.

Name Description Paths
id The logical resource id associated with the resource (must be supported by all servers)
family A portion of the family name Practitioner.name
gender Gender of the practitioner Practitioner.gender
given A portion of the given name Practitioner.name
identifier A practitioner’s Identifier Practitioner.identifier
organization The identity of the organization the practitioner represents / acts on behalf of Practitioner.organization(Organization)
telecom The value in any kind of contact Practitioner.telecom

Examples

Query Results Try it!
GET /practitioners/b7c2de52-3f38-4879-ad55-d3f67b3ecc4c Retrieve a specific organization by its ID. In the general context and for most use cases, the developer should have this ID already available. The only context in which the ID might not be available is in the context of an HIE and a query that needs to pull in information about a specific patient from across multiple organizations. This, of course, has significant security and access control challenges. SO we’ll leave that out for the time being.
GET /practitioners?identifier=5139849898 This identifier could be anything such as NPI number, DEA number, D&B etc. Note that these must be organization level identifiers. Provider level identifiers, will of course, not work in this context.
GET /practitioners?family=Carter&given=Michelle&specialty=cardio The name parameter is enabled in this Catalyze implementation but in a real life deployment there can be multitude of matches to a name. Which also implies possibly a central authority with identifiers of all organizations. A full listing of specialties is available here
GET /practitioners/b7c2de52-3f38-4879-ad55-d3f67b3ecc4c
    { 
      "practitioners" : [ 
        { 
          "resourceType" : "Practitioner",
          "id" : "b7c2de52-3f38-4879-ad55-d3f67b3ecc4c",
          "identifier" : [ 
            { 
              "use" : "official",
              "label" : "DEA",
              "system" : "http://snomed.info/sct",
              "value" : "A2513786"
              },
            { 
              "use" : "official",
              "label" : "NPI",
              "system" : "http://snomed.info/sct",
              "value" : "7689849898"
              }
            ],
          "name" : { 
            "use" : "official",
            "family" : [ 
              "White"
              ],
            "given" : [ 
              "Terry"
              ],
            "prefix" : [ 
              "Dr."
              ]
            },
          "telecom" : [ 
            { 
              "system" : "phone",
              "value" : "980-500-3486",
              "use" : "work"
              }
            ],
          "address" : { 
            "use" : "work",
            "line" : [ 
              "846  Quis , Apt 690"
              ],
            "city" : "Davis",
            "zip" : "48951"
            },
          "gender" : { 
            "coding" : [ 
              { 
                "system" : "http://snomed.info/sct",
                "code" : "248152002",
                "display" : "Female"
                }
              ]
            },
          "birthDate" : "1974-06-20",
          "organization" : { 
            "reference" : "Organization/2a6fbe28-a851-44cb-b54e-77c1eadc2475"
            },
          "role" : [ 
            { 
              "coding" : [
                ]
              }
            ],
          "specialty" : [ 
            { 
              "coding" : [ 
                { 
                  "system" : "http://snomed.info/sct",
                  "code" : "394733009",
                  "display" : "Cardiologist"
                  }
                ]
              }
            ],
          "qualification" : [ 
            { 
              "code" : { 
                "coding" : [ 
                  { 
                    "system" : "http://snomed.info/sct",
                    "code" : "394603008",
                    "display" : "Cardiothoracic surgery"
                    }
                  ]
                }
              }
            ]
          }
        ]
      }
GET /practitioners?identifier=5139849898
        { 
      "practitioners" : [ 
        { 
          "resourceType" : "Practitioner",
          "id" : "b7c2de52-3f38-4879-ad55-d3f67b3ecc4c",
          "identifier" : [ 
            { 
              "use" : "official",
              "label" : "NPI",
              "system" : "http://snomed.info/sct",
              "value" : "5139849898"
              }
            ],
          "name" : { 
            "use" : "official",
            "family" : [ 
              "Brown"
              ],
            "given" : [ 
              "Janine"
              ],
            "prefix" : [ 
              "Dr."
              ]
            },
          "telecom" : [ 
            { 
              "system" : "phone",
              "value" : "733-557-0426",
              "use" : "work"
              }
            ],
          "address" : { 
            "use" : "work",
            "line" : [ 
              "979  Magna , Apt 773"
              ],
            "city" : "Gonzalez",
            "zip" : "63805"
            },
          "gender" : { 
            "coding" : [ 
              { 
                "system" : "http://snomed.info/sct",
                "code" : "248152002",
                "display" : "Female"
                }
              ]
            },
          "birthDate" : "1974-08-18",
          "organization" : { 
            "reference" : "Organization/1bbf798f-e2a4-4539-bede-63f38f02d8a4"
            },
          "role" : [ 
            { 
              "coding" : [
                ]
              }
            ],
          "specialty" : [ 
            { 
              "coding" : [ 
                { 
                  "system" : "http://snomed.info/sct",
                  "code" : "394733009",
                  "display" : "Cardiologist"
                  }
                ]
              }
            ],
          "qualification" : [ 
            { 
              "code" : { 
                "coding" : [ 
                  { 
                    "system" : "http://snomed.info/sct",
                    "code" : "394603008",
                    "display" : "Cardiothoracic surgery"
                    }
                  ]
                }
              }
            ]
          }
        ]
      }
GET /practitioners?family=Carter&given=Michelle&specialty=cardio
    { 
      "practitioners" : [ 
        { 
          "resourceType" : "Practitioner",
          "id" : "6d3d41a4-bc59-49ba-bf5d-23e25a3622e8",
          "identifier" : [ 
            { 
              "use" : "official",
              "label" : "NPI",
              "system" : "http://snomed.info/sct",
              "value" : "5242458577"
              }
            ],
          "name" : { 
            "use" : "official",
            "family" : [ 
              "Carter"
              ],
            "given" : [ 
              "Michelle"
              ],
            "prefix" : [ 
              "Dr."
              ]
            },
          "telecom" : [ 
            { 
              "system" : "phone",
              "value" : "358-831-2331",
              "use" : "work"
              }
            ],
          "address" : { 
            "use" : "work",
            "line" : [ 
              "607  Cillum , Apt 234"
              ],
            "city" : "White",
            "zip" : "06730"
            },
          "gender" : { 
            "coding" : [ 
              { 
                "system" : "http://snomed.info/sct",
                "code" : "248152002",
                "display" : "Female"
                }
              ]
            },
          "birthDate" : "1974-03-18",
          "organization" : { 
            "reference" : "Organization/ce7509ca-bdc3-4198-b802-99845fd6d06d"
            },
          "role" : [ 
            { 
              "coding" : [
                ]
              }
            ],
          "specialty" : [ 
            { 
              "coding" : [ 
                { 
                  "system" : "http://snomed.info/sct",
                  "code" : "394733009",
                  "display" : "Cardiologist"
                  }
                ]
              }
            ],
          "qualification" : [ 
            { 
              "code" : { 
                "coding" : [ 
                  { 
                    "system" : "http://snomed.info/sct",
                    "code" : "394603008",
                    "display" : "Cardiothoracic surgery"
                    }
                  ]
                }
              }
            ]
          }
        ]
      }

Allergy Intolerance, Adverse Reaction & Substance Resources

While these are documented as separate resources on the FHIR, it does make sense to combine these three into a single set of descriptions as they are closely linked to each other. The FHIR AllergyIntolerance resource defines clinical information about a patient’s allergic response to a substance. The AllergyIntolerance resource defines the substance that elicited the response, as well as when the reaction occured, the severity, and the type of reaction noted. Much of this information is documented in the AdverseReaction resource as well, associating the two resources for the complete clinical documentation of an allergy. The Substance resource provides additional detail about the allergen.

Allergy Intolerance FHIR API route

As described above, the FHIR AllergyIntolerance resource defines clinical information about a patient’s allergic response to a substance. The AllergyIntolerance resource defines the substance that elicited the response, as well as when the reaction occured, the severity, and the type of reaction noted. A full listing of all the fields is available here.

The general route should be as follows. Note that the response from the server should ideally be a bundled resource i.e. containing information on the substance(s) to which the patient has an allergic reaction and the adverse reactions to those substances. Click on the examples below to see what the bundled resource response could look like.

GET /allergyIntolerance?params=value

Possible / allowed parameters

Acceptable values of parameters will be dependent on the specific information and should be accessible via the conformance request. However, a minimal set that can be expected to be supported are shown in the table below. These are also supported in the Catalyze FHIR API. Again note that all animal related paths have been eliminated here.

Name Description Paths
id The logical resource id associated with the resource (must be supported by all servers)
date Recorded date/time allergyIntolerance.recordedDate
recorder The individual who recorded the sensitivity i.e. patient or practioner / provider allergyIntolerance.recorder (Patient, Practitioner)
status The status of the sensitivity allergyIntolerance.status
subject The specific patient that the sensitivity is about allergyIntolerance.subject (Patient)
substance The name or code of the substance that produces the sensitivity allergyIntolerance.substance (Substance)
criticality The criticality of the response. Only allowed value as listed here i.e. fatal, high, medium, low allergyIntolerance.criticality
type The type of sensitivity allergyIntolerance.sensitivityType

Examples

Query Results Try it!
GET /allergyIntolerance?subject=22283003-8c26-4b24-bbe9-b38756908eb5 List of allergies with for that specific patient
GET /allergyIntolerance?subject=22283003-8c26-4b24-bbe9-b38756908eb5&criticality=fatal List of allergies specific patient has fatal reaction to
GET /allergyIntolerance/05328edd-7c97-4d6b-b8f1-bdacfa1215fa Allergy with that specific identifier. This usally assumes that the lookup has happened by patient already and a specific ID has been retrieved that you might need additional details around or it could be used in a subsequent read operation without having to make a full patient query again
GET /allergyIntolerance?subject=22283003-8c26-4b24-bbe9-b38756908eb5&substance=253294bc-b747-4458-818e-52551cd0d742 A specific patient’s reaction to a specific substance. Note that the identifier is required in advance. A full search so a query like substance=penicillin or a snomed code substance=323389000would be ideal
GET /allergyIntolerance?subject=22283003-8c26-4b24-bbe9-b38756908eb5
        { 
  "allergyIntolerance" : [ 
    { 
      "resourceType" : "Bundle",
      "title" : "Search results for AllergyIntolerance",
      "entry" : [ 
        { 
          "title" : "Entry for AllergyIntolerance",
          "id" : "05328edd-7c97-4d6b-b8f1-bdacfa1215fa",
          "updated" : "2015-05-16T10:47:49",
          "published" : "2015-05-16T10:47:49",
          "content" : { 
            "resourceType" : "allergyIntolerance",
            "recordedDate" : "1994-05-31",
            "status" : "confirmed",
            "sensitivityType" : "unknown",
            "criticality" : "low",
            "identifier" : [ 
              { 
                "value" : "612",
                "use" : "usual"
                }
              ],
            "subject" : { 
              "reference" : "patient/22283003-8c26-4b24-bbe9-b38756908eb5",
              "display" : "Jason White"
              },
            "substance" : { 
              "reference" : "substance/6558292e-d308-4742-9be0-53a5d42472ba",
              "display" : "Penicillin"
              },
            "reaction" : [ 
              { 
                "reference" : "/AdverseReaction/1168ad5b-3d77-4fd9-8bb4-20170d43744b",
                "display" : "Hives"
                },
              { 
                "reference" : "/AdverseReaction/cdda0bf2-07f4-407c-9621-0882e2c54fd3",
                "display" : "Sneezing"
                }
              ]
            }
          },
        { 
          "title" : "Entry for AllergyIntolerance",
          "id" : "1ad2d3eb-971e-434c-b555-0cc084bf106c",
          "updated" : "2015-05-16T10:47:49",
          "published" : "2015-05-16T10:47:49",
          "content" : { 
            "resourceType" : "allergyIntolerance",
            "recordedDate" : "1997-12-02",
            "status" : "confirmed",
            "sensitivityType" : "allergy",
            "criticality" : "fatal",
            "identifier" : [ 
              { 
                "value" : "237",
                "use" : "official"
                }
              ],
            "subject" : { 
              "reference" : "patient/22283003-8c26-4b24-bbe9-b38756908eb5",
              "display" : "Jason White"
              },
            "substance" : { 
              "reference" : "substance/ad79760b-64e6-4b46-9abc-b77811e23398",
              "display" : "Bee Sting"
              },
            "reaction" : [ 
              { 
                "reference" : "/AdverseReaction/ad5aaa54-010c-47e1-b9bb-d536038ac9ac",
                "display" : "Hives"
                },
              { 
                "reference" : "/AdverseReaction/9c7f9a3a-822a-4c74-b0f9-c26c162a6858",
                "display" : "Anaphylaxis"
                }
              ]
            }
          },
        { 
          "title" : "Entry for AllergyIntolerance",
          "id" : "6bf9e863-1c76-405f-bd5f-894782d84ecc",
          "updated" : "2015-05-16T10:47:49",
          "published" : "2015-05-16T10:47:49",
          "content" : { 
            "resourceType" : "allergyIntolerance",
            "recordedDate" : "1970-06-01",
            "status" : "confirmed",
            "sensitivityType" : "allergy",
            "criticality" : "high",
            "identifier" : [ 
              { 
                "value" : "713",
                "use" : "official"
                }
              ],
            "subject" : { 
              "reference" : "patient/22283003-8c26-4b24-bbe9-b38756908eb5",
              "display" : "Jason White"
              },
            "substance" : { 
              "reference" : "substance/253294bc-b747-4458-818e-52551cd0d742",
              "display" : "House Dust"
              },
            "reaction" : [ 
              { 
                "reference" : "/AdverseReaction/cdda0bf2-07f4-407c-9621-0882e2c54fd3",
                "display" : "Swelling"
                },
              { 
                "reference" : "/AdverseReaction/ad5aaa54-010c-47e1-b9bb-d536038ac9ac",
                "display" : "Itchy Eyes"
                }
              ]
            }
          }
        ]
      }
    ]
  }
GET /allergyIntolerance?subject=22283003-8c26-4b24-bbe9-b38756908eb5&criticality=fatal
        { 
  "allergyIntolerance" : [ 
    { 
      "resourceType" : "Bundle",
      "title" : "Search results for AllergyIntolerance",
      "entry" : [ 
        { 
          "title" : "Entry for AllergyIntolerance",
          "id" : "1ad2d3eb-971e-434c-b555-0cc084bf106c",
          "updated" : "2015-05-16T10:47:49",
          "published" : "2015-05-16T10:47:49",
          "content" : { 
            "resourceType" : "allergyIntolerance",
            "recordedDate" : "1997-12-02",
            "status" : "confirmed",
            "sensitivityType" : "allergy",
            "criticality" : "fatal",
            "identifier" : [ 
              { 
                "value" : "237",
                "use" : "official"
                }
              ],
            "subject" : { 
              "reference" : "patient/22283003-8c26-4b24-bbe9-b38756908eb5",
              "display" : "Jason White"
              },
            "substance" : { 
              "reference" : "substance/ad79760b-64e6-4b46-9abc-b77811e23398",
              "display" : "Bee Sting"
              },
            "reaction" : [ 
              { 
                "reference" : "/AdverseReaction/ad5aaa54-010c-47e1-b9bb-d536038ac9ac",
                "display" : "Hives"
                },
              { 
                "reference" : "/AdverseReaction/9c7f9a3a-822a-4c74-b0f9-c26c162a6858",
                "display" : "Anaphylaxis"
                }
              ]
            }
          }
        ]
      }
    ]
  }
GET /allergyIntolerance/05328edd-7c97-4d6b-b8f1-bdacfa1215fa
        { 
  "allergyIntolerance" : [ 
    { 
      "resourceType" : "Bundle",
      "title" : "Search results for AllergyIntolerance",
      "entry" : [ 
        { 
          "title" : "Entry for AllergyIntolerance",
          "id" : "05328edd-7c97-4d6b-b8f1-bdacfa1215fa",
          "updated" : "2015-05-16T10:47:49",
          "published" : "2015-05-16T10:47:49",
          "content" : { 
            "resourceType" : "allergyIntolerance",
            "recordedDate" : "1994-05-31",
            "status" : "confirmed",
            "sensitivityType" : "unknown",
            "criticality" : "low",
            "identifier" : [ 
              { 
                "value" : "612",
                "use" : "usual"
                }
              ],
            "subject" : { 
              "reference" : "patient/22283003-8c26-4b24-bbe9-b38756908eb5",
              "display" : "Jason White"
              },
            "substance" : { 
              "reference" : "substance/6558292e-d308-4742-9be0-53a5d42472ba",
              "display" : "Penicillin"
              },
            "reaction" : [ 
              { 
                "reference" : "/AdverseReaction/1168ad5b-3d77-4fd9-8bb4-20170d43744b",
                "display" : "Hives"
                },
              { 
                "reference" : "/AdverseReaction/cdda0bf2-07f4-407c-9621-0882e2c54fd3",
                "display" : "Sneezing"
                }
              ]
            }
          }
        ]
      }
    ]
  }
GET /allergyIntolerance?subject=22283003-8c26-4b24-bbe9-b38756908eb5&substance=253294bc-b747-4458-818e-52551cd0d742
    { 
      "allergyIntolerance" : [ 
        { 
          "resourceType" : "Bundle",
          "title" : "Search results for AllergyIntolerance",
          "entry" : [ 
            { 
              "title" : "Entry for AllergyIntolerance",
              "id" : "6bf9e863-1c76-405f-bd5f-894782d84ecc",
              "updated" : "2015-05-16T10:47:49",
              "published" : "2015-05-16T10:47:49",
              "content" : { 
                "resourceType" : "allergyIntolerance",
                "recordedDate" : "1970-06-01",
                "status" : "confirmed",
                "sensitivityType" : "allergy",
                "criticality" : "high",
                "identifier" : [ 
                  { 
                    "value" : "713",
                    "use" : "official"
                    }
                  ],
                "subject" : { 
                  "reference" : "patient/22283003-8c26-4b24-bbe9-b38756908eb5",
                  "display" : "Jason White"
                  },
                "substance" : { 
                  "reference" : "substance/253294bc-b747-4458-818e-52551cd0d742",
                  "display" : "House Dust"
                  },
                "reaction" : [ 
                  { 
                    "reference" : "/AdverseReaction/cdda0bf2-07f4-407c-9621-0882e2c54fd3",
                    "display" : "Swelling"
                    },
                  { 
                    "reference" : "/AdverseReaction/ad5aaa54-010c-47e1-b9bb-d536038ac9ac",
                    "display" : "Itchy eyes"
                    }
                  ]
                }
              }
            ]
          }
        ]
      }

Adverse Reaction FHIR API route

This route is intended to allow a query for all the reactions associated with a specific patient’s medical history. This requires that a patient specific query has already been made and the ID of the particular patient for which this data is required is available. A full listing of all the fields is available here.

The general route should be as follows.

GET /adverseReaction?params=value

Possible / allowed parameters

Acceptable values of parameters will be dependent on the specific information and should be accessible via the conformance request. However, a minimal set that can be expected to be supported are shown in the table below. These are also supported in the Catalyze FHIR API. Again note that all animal related paths have been eliminated here.

Name Description Paths
id The logical resource id associated with the resource (must be supported by all servers)
date The date of the reaction adverseReaction.date
subject The subject that the sensitivity is about adverseReaction.subject (Patient)
substance The name or code of the substance that produces the sensitivity adverseReaction.exposure.substance (Substance)
symptom One of the symptoms of the reaction adverseReaction.symptom.code

Examples

Query Results Try it!
GET /adverseReaction/05328edd-7c97-4d6b-b8f1-bdacfa1215fa Specific adverse reaction resource with that identifier. This usally assumes that the lookup has happened by patient already and a specific ID has been retrieved that you might need additional details around or it could be used in a subsequent read operation without having to make a full patient query again
GET /adverseReaction?subject=22283003-8c26-4b24-bbe9-b38756908eb5&substance=253294bc-b747-4458-818e-52551cd0d742 or GET /adverseReaction?subject=22283003-8c26-4b24-bbe9-b38756908eb5&substance=323389000 A full search so a query like substance=penicillin or a snomed code substance=323389000would be ideal
GET /adverseReaction/05328edd-7c97-4d6b-b8f1-bdacfa1215fa
    { 
      "adverseReactions" : [ 
        { 
          "resourceType" : "AdverseReaction",
          "id":"05328edd-7c97-4d6b-b8f1-bdacfa1215fa",
          "date" : "2015-05-16",
          "subject" : { 
            "reference" : "Patient/d4033832-ff62-4dd2-9465-e09a73f9683f"
            },
          "didNotOccurFlag" : false,
          "recorder" : { 
            "reference" : "Practitioner/c8e23a8a-cd7d-48d3-94c8-642f6c3af6ed"
            },
          "symptom" : [ 
            { 
              "code" : { 
                "coding" : [ 
                  { 
                    "system" : "http://hl7.org/fhir/sid/icd-10",
                    "code" : "T78.2","display" : "Anaphylactic shock, unspecified"
                    }
                  ],
                "severity" : "severe"
                }
              }
            ],
          "exposure" : [ 
            { 
              "date" : "2015-10-04",
              "type" : "coincidental",
              "substance" : { 
                "reference" : "Substance/ba0e8c0e-df45-49c5-9147-bba158db70b9"
                }
              }
            ]
          }
        ]
      }
GET /adverseReaction?subject=22283003-8c26-4b24-bbe9-b38756908eb5&substance=253294bc-b747-4458-818e-52551cd0d742
    { 
      "adverseReactions" : [ 
        { 
          "resourceType" : "AdverseReaction",
          "id":"7384c20b-ea94-4abf-9a18-0357e8813587",
          "date" : "2015-05-16",
          "subject" : { 
            "reference" : "Patient/22283003-8c26-4b24-bbe9-b38756908eb5"
            },
          "didNotOccurFlag" : false,
          "recorder" : { 
            "reference" : "Practitioner/c8e23a8a-cd7d-48d3-94c8-642f6c3af6ed"
            },
          "symptom" : [ 
            { 
              "code" : { 
                "coding" : [ 
                  { 
                    "system" : "http://hl7.org/fhir/sid/icd-10",
                    "code" : "T78.2","display" : "Anaphylactic shock, unspecified"
                    }
                  ],
                "severity" : "severe"
                }
              }
            ],
          "exposure" : [ 
            { 
              "date" : "2015-10-04",
              "type" : "coincidental",
              "substance" : { 
                "reference" : "Substance/253294bc-b747-4458-818e-52551cd0d742"
                }
              }
            ]
          }
        ]
      }

Substance FHIR API route

The substance route doesn’t really make sense since all it does is identify a specific drug, or any other item that has some clinical bearing. It is not patient specific at all and shouldn’t be. Any item that has a clinical bearing (and even otherwise) is already well covered by various coding standards such as SNOMED. In fact, the substance resource is essentially that - a SNOMED code. Which begs the question, why not just drop this resource and its associated route and just make the query using the substance’s SNOMED (or ICD or LOINC) code or name? We will ignore this route for now. If you are still interested in this route and associated resource model, full details are available here

Medication Prescription & Medication Resource

While these are documented as separate resources on the FHIR, it does make sense to combine these three into a single set of descriptions as they are closely linked to each other.

Medication Prescription FHIR API route

The FHIR medicationPrescription resource defines detailed information about a medication that was ordered for a patient. This includes medications administered during a hospitalization as well as prescriptions or OTC drugs ordered in an ambulatory clinic. It is not used for diet orders or durable medical equipment. It also contains information about how the medication should be taken by or given to the patient. A full listing of all the fields is available here.

The general route should be as follows. Note that the response from the server should ideally be a bundled resource i.e. containing information on the substance(s) to which the patient has an allergic reaction and the adverse reactions to those substances. Click on the examples below to see what the bundled resource response could look like. Note that the FHIR documentation uses the full name of this resource in all API calls which can get very lengthy and cumbersome (and could also run into length limits in some frameworks) so you can expect these to get shortened (medicationRx perhaps would have been a better choice?). Anwyays, we’ll stick with the standard to minimize confusion.

GET /medicationPrescription?params=value

Possible / allowed parameters

Acceptable values of parameters will be dependent on the specific information and should be accessible via the conformance request. However, a minimal set that can be expected to be supported are shown in the table below. These are also supported in the Catalyze FHIR API. Again note that all animal related paths have been eliminated here.

Name Description Paths
id The logical resource id associated with the resource (must be supported by all servers)
dateWritten Return prescriptions written on this date medicationPrescription.dateWritten
encounter Return prescriptions with this encounter identity medicationPrescription.encounter (Encounter)
identifier Return prescriptions with this external identity medicationPrescription.identifier
medication Code for medicine or text in medicine name medicationPrescription.medication (Medication)
patient The identity of a patient to list dispenses for medicationPrescription.patient (Patient). Note that this is inconsistent with the way in which a patient is referred to in other routes. We will use the standard definition for now. But ideally this should have been subject not patient
status Status of the prescription medicationPrescription.status

Examples

Query Results Try it!
GET /medicationPrescription?patient=22283003-8c26-4b24-bbe9-b38756908eb5 This will return all the medications ever (?) for that specific patient. Note that the response will be a resource bundle.
GET /medicationPrescription?patient=22283003-8c26-4b24-bbe9-b38756908eb5&status=active This will return all the active medications for that specific patient. Note that the response will be a resource bundle.
GET /medicationPrescription/037499b0-ebb4-4336-a9ec-a751e6feb717 Retrieve a specific prescription by its ID. This usally assumes that the lookup has happened by patient already and a specific ID has been retrieved that you might need additional details around or it could be used in a subsequent read operation without having to make a full patient query again
GET /medicationPrescription/037499b0-ebb4-4336-a9ec-a751e6feb717
    { 
      "medicationPrescription" : [ 
        { 
          "resourceType" : "Bundle",
          "entry" : [ 
            { 
              "title" : "Entry for MedicationPrescription",
              "id" : "037499b0-ebb4-4336-a9ec-a751e6feb717",
              "updated" : "2015-04-15 T13:10:28",
              "published" : "2015-02-30 T13:10:28",
              "content" : { 
                "resourceType" : "MedicationPrescription",
                "dateWritten" : "1980-06-13 T13:10:28",
                "status" : "suspended",
                "identifier" : [ 
                  { 
                    "value" : "895520",
                    "system" : "urn:oid:1.2.840.114350.1.13.327.1.7.2.798268",
                    "use" : "usual"
                    },
                  { 
                    "value" : "895520",
                    "system" : "urn:oid:1.2.840.114350.1.13.327.1.7.2.798268",
                    "use" : "usual"
                    }
                  ],
                "patient" : { 
                  "reference" : "patient/22283003-8c26-4b24-bbe9-b38756908eb5",
                  "display" : "James White"
                  },
                "prescriber" : { 
                  "reference" : "Practitioner/c8e23a8a-cd7d-48d3-94c8-642f6c3af6ed"
                  },
                "medication" : { 
                  "reference" : "medication/22a3e091-448c-427a-9215-0ba150d7ec53",
                  "display" : "LEVOTHYROXINE 100 MCG tablet"
                  },
                "dosageInstruction" : [
                  ],
                "dispense" : { 
                  "numberOfRepeatsAllowed" : 0,
                  "quantity" : { 
                    "value" : 250,
                    "system" : "urn:oid:1.2.840.114350.1.13.327.1.7.4.696784.9010",
                    "code" : "5002"
                    }
                  }
                }
              }
            ]
          }
        ]
      }
GET /medicationPrescription?patient=22283003-8c26-4b24-bbe9-b38756908eb5
    { 
      "medicationPrescription" : [ 
        { 
          "resourceType" : "Bundle",
          "entry" : [ 
            { 
              "title" : "Entry for MedicationPrescription",
              "id" : "037499b0-ebb4-4336-a9ec-a751e6feb717",
              "updated" : "2015-04-15 T13:10:28",
              "published" : "2015-02-30 T13:10:28",
              "content" : { 
                "resourceType" : "MedicationPrescription",
                "dateWritten" : "1980-06-13 T13:10:28",
                "status" : "suspended",
                "identifier" : [ 
                  { 
                    "value" : "895520",
                    "system" : "urn:oid:1.2.840.114350.1.13.327.1.7.2.798268",
                    "use" : "usual"
                    },
                  { 
                    "value" : "895520",
                    "system" : "urn:oid:1.2.840.114350.1.13.327.1.7.2.798268",
                    "use" : "usual"
                    }
                  ],
                "patient" : { 
                  "reference" : "patient/22283003-8c26-4b24-bbe9-b38756908eb5",
                  "display" : "James White"
                  },
                "prescriber" : { 
                  "reference" : "Practitioner/c8e23a8a-cd7d-48d3-94c8-642f6c3af6ed"
                  },
                "medication" : { 
                  "reference" : "medication/22a3e091-448c-427a-9215-0ba150d7ec53",
                  "display" : "LEVOTHYROXINE 100 MCG tablet"
                  },
                "dosageInstruction" : [
                  ],
                "dispense" : { 
                  "numberOfRepeatsAllowed" : 0,
                  "quantity" : { 
                    "value" : 250,
                    "system" : "urn:oid:1.2.840.114350.1.13.327.1.7.4.696784.9010",
                    "code" : "5002"
                    }
                  }
                }
              },
            { 
              "title" : "Entry for MedicationPrescription",
              "id" : "9508c707-ef5d-45e5-81c9-7d1a256acb1c",
              "updated" : "2015-02-28 T13:10:28",
              "published" : "2015-10-10 T13:10:28",
              "content" : { 
                "resourceType" : "MedicationPrescription",
                "dateWritten" : "1986-10-31 T13:10:28",
                "status" : "active",
                "identifier" : [ 
                  { 
                    "value" : "895520",
                    "system" : "urn:oid:1.2.840.114350.1.13.327.1.7.2.798268",
                    "use" : "usual"
                    },
                  { 
                    "value" : "895520",
                    "system" : "urn:oid:1.2.840.114350.1.13.327.1.7.2.798268",
                    "use" : "usual"
                    }
                  ],
                "patient" : { 
                  "reference" : "patient/22283003-8c26-4b24-bbe9-b38756908eb5",
                  "display" : "James White"
                  },
                "prescriber" : { 
                  "reference" : "Practitioner/151372a1-f19e-4e8f-8b01-ab7bbcc5facc"
                  },
                "medication" : { 
                  "reference" : "medication/786eefc0-bde5-4715-a965-503e3769579f",
                  "display" : "SIMVASTATIN 40 MG tablet"
                  },
                "dosageInstruction" : [
                  ],
                "dispense" : { 
                  "numberOfRepeatsAllowed" : 3,
                  "quantity" : { 
                    "value" : 250,
                    "system" : "urn:oid:1.2.840.114350.1.13.327.1.7.4.696784.9010",
                    "code" : "5002"
                    }
                  }
                }
              },
            { 
              "title" : "Entry for MedicationPrescription",
              "id" : "c4f035c2-07b9-4e75-9543-aeb5faf55cb9",
              "updated" : "2015-07-02 T13:10:28",
              "published" : "2015-11-29 T13:10:28",
              "content" : { 
                "resourceType" : "MedicationPrescription",
                "dateWritten" : "2008-08-13 T13:10:28",
                "status" : "active",
                "identifier" : [ 
                  { 
                    "value" : "895520",
                    "system" : "urn:oid:1.2.840.114350.1.13.327.1.7.2.798268",
                    "use" : "usual"
                    }
                  ],
                "patient" : { 
                  "reference" : "patient/22283003-8c26-4b24-bbe9-b38756908eb5",
                  "display" : "James White"
                  },
                "prescriber" : { 
                  "reference" : "Practitioner/b7c2de52-3f38-4879-ad55-d3f67b3ecc4c"
                  },
                "medication" : { 
                  "reference" : "medication/93943bff-b2ba-4125-a128-d0cc06772a62",
                  "display" : "DILTIAZEM 240 MG ER capsule"
                  },
                "dosageInstruction" : [
                  ],
                "dispense" : { 
                  "numberOfRepeatsAllowed" : 0,
                  "quantity" : { 
                    "value" : 250,
                    "system" : "urn:oid:1.2.840.114350.1.13.327.1.7.4.696784.9010",
                    "code" : "5002"
                    }
                  }
                }
              },
            { 
              "title" : "Entry for MedicationPrescription",
              "id" : "0c59d40c-838f-4f6e-81c2-991519c98561",
              "updated" : "2015-02-10 T13:10:28",
              "published" : "2015-09-13 T13:10:28",
              "content" : { 
                "resourceType" : "MedicationPrescription",
                "dateWritten" : "2003-01-05 T13:10:28",
                "status" : "suspended",
                "identifier" : [ 
                  { 
                    "value" : "895520",
                    "system" : "urn:oid:1.2.840.114350.1.13.327.1.7.2.798268",
                    "use" : "usual"
                    },
                  { 
                    "value" : "895520",
                    "system" : "urn:oid:1.2.840.114350.1.13.327.1.7.2.798268",
                    "use" : "usual"
                    }
                  ],
                "patient" : { 
                  "reference" : "patient/22283003-8c26-4b24-bbe9-b38756908eb5",
                  "display" : "James White"
                  },
                "prescriber" : { 
                  "reference" : "Practitioner/c8e23a8a-cd7d-48d3-94c8-642f6c3af6ed"
                  },
                "medication" : { 
                  "reference" : "medication/3c64d504-9290-455c-a359-e518fee128bb",
                  "display" : "DILTIAZEM 240 MG ER capsule"
                  },
                "dosageInstruction" : [
                  ],
                "dispense" : { 
                  "numberOfRepeatsAllowed" : 2,
                  "quantity" : { 
                    "value" : 250,
                    "system" : "urn:oid:1.2.840.114350.1.13.327.1.7.4.696784.9010",
                    "code" : "5002"
                    }
                  }
                }
              }
            ]
          }
        ]
      }
GET /medicationPrescription?patient=22283003-8c26-4b24-bbe9-b38756908eb5&status=active
    { 
      "medicationPrescription" : [ 
        { 
          "resourceType" : "Bundle",
          "entry" : [ 
            { 
              "title" : "Entry for MedicationPrescription",
              "id" : "9508c707-ef5d-45e5-81c9-7d1a256acb1c",
              "updated" : "2015-02-28 T13:10:28",
              "published" : "2015-10-10 T13:10:28",
              "content" : { 
                "resourceType" : "MedicationPrescription",
                "dateWritten" : "1986-10-31 T13:10:28",
                "status" : "active",
                "identifier" : [ 
                  { 
                    "value" : "895520",
                    "system" : "urn:oid:1.2.840.114350.1.13.327.1.7.2.798268",
                    "use" : "usual"
                    },
                  { 
                    "value" : "895520",
                    "system" : "urn:oid:1.2.840.114350.1.13.327.1.7.2.798268",
                    "use" : "usual"
                    }
                  ],
                "patient" : { 
                  "reference" : "patient/22283003-8c26-4b24-bbe9-b38756908eb5",
                  "display" : "James White"
                  },
                "prescriber" : { 
                  "reference" : "Practitioner/151372a1-f19e-4e8f-8b01-ab7bbcc5facc"
                  },
                "medication" : { 
                  "reference" : "medication/786eefc0-bde5-4715-a965-503e3769579f",
                  "display" : "SIMVASTATIN 40 MG tablet"
                  },
                "dosageInstruction" : [
                  ],
                "dispense" : { 
                  "numberOfRepeatsAllowed" : 3,
                  "quantity" : { 
                    "value" : 250,
                    "system" : "urn:oid:1.2.840.114350.1.13.327.1.7.4.696784.9010",
                    "code" : "5002"
                    }
                  }
                }
              },
            { 
              "title" : "Entry for MedicationPrescription",
              "id" : "c4f035c2-07b9-4e75-9543-aeb5faf55cb9",
              "updated" : "2015-07-02 T13:10:28",
              "published" : "2015-11-29 T13:10:28",
              "content" : { 
                "resourceType" : "MedicationPrescription",
                "dateWritten" : "2008-08-13 T13:10:28",
                "status" : "active",
                "identifier" : [ 
                  { 
                    "value" : "895520",
                    "system" : "urn:oid:1.2.840.114350.1.13.327.1.7.2.798268",
                    "use" : "usual"
                    }
                  ],
                "patient" : { 
                  "reference" : "patient/22283003-8c26-4b24-bbe9-b38756908eb5",
                  "display" : "James White"
                  },
                "prescriber" : { 
                  "reference" : "Practitioner/b7c2de52-3f38-4879-ad55-d3f67b3ecc4c"
                  },
                "medication" : { 
                  "reference" : "medication/93943bff-b2ba-4125-a128-d0cc06772a62",
                  "display" : "DILTIAZEM 240 MG ER capsule"
                  },
                "dosageInstruction" : [
                  ],
                "dispense" : { 
                  "numberOfRepeatsAllowed" : 0,
                  "quantity" : { 
                    "value" : 250,
                    "system" : "urn:oid:1.2.840.114350.1.13.327.1.7.4.696784.9010",
                    "code" : "5002"
                    }
                  }
                }
              }
            ]
          }
        ]
      }

Medication FHIR API route

The FHIR medication resource defines detailed information about a medication product or a medication package. The Medication resource is not specific to any patient. This route also doesn’t really make sense since all it does is identify a specific drug and associated packaging and other information. It is not patient specific at all and shouldn’t be. Any item that has a clinical bearing (and even otherwise) is already well covered by various coding standards. This kind of information is publicly avaiable via commerical vendors who are unlikely to allow unlimited access to this data. Public data sources like RxNORM also exist which can supply this same information. All these sources are constantly maintained and cleansed. Re-storing this data in an EHR and then ensuring it is updated etc. is an unnecessary process.

Which begs the question, why not just drop this resource and its associated route and just make the query using the drug’s RxNORM (or other) code or name. We will ignore this route for now. If you are still interested in this route and associated resource model, full details are available here