SAFHIR API Documentation. Links to Capability Statements, Swagger documentation and FHIR Implementation guides to assist developers implement support for the Patient Access API covered by the CMS Interoperability and Patient Access Rule released in May 2020.

Background

When CMS issued the Interoperability and Patient Access Rule in May 2020 they provided guidance that adopting a set of HL7 Implementation Guides (IG) would enable the payers that are covered by the rule to achieve compliance. The Relevant implementation Guides are:

The Payer Data Exchange (PDex) IG incorporates the data profiles defined in the US Core 3.1.1 IG.

The PDex Plan-Net IG differs from the other IGs in that it does not require member authentication and authorization in order to access the API. Plan-Net is an Open API.

Accessing the APIs

The Patient Access APIs require that each application has a set of app credentials. These credentials are used in an OAuth2.0/SMART-on-FHIR access authorization flow that enables the individual member to grant a registered app to access their data.

To register an app Developers can go to the SAFHIR Developer Portal.

SAFHIR, the Interoperability Rule and FHIR Implementation Guides

The SAFHIR platform has been designed to convert FHIR Implementation Guides into APIs. SAFHIR can ingest a capability statement and create the required APIs together with the relevant member-level access controls.

In order to comply with the CMS Interoperability Rule we provide access to the following resources to support developers who are creating applications that make use of the IGs identified in the previous section.

Implementation Guides

For developers who are not familiar with HL7 FHIR Implementation Guides (IGs). An IG provides detailed information on data structures for resource profiles. It also provides information on Search parameters and other technical aspects of the use cases that the IG was designed to address. Each IG builds on the base FHIR Release 4 specification for elements such as, field definitions and data types.

You are strongly encouraged to refer to the introductory sections of each IG. The introduction will provide a context to the use cases the guide addresses. This can have implications for how the information is accessed and the type of searches that are supported.

The links to each guide are provided below:

Capability Statements

Server Capability Statements define the data profiles, operations, access methods and search operations that are supported by the server.

The Capability Statement can be referenced using the [base_url][/ig_name]/metadata endpoint.

Implementation Guide IG Short Name CapabilityStatement Link
CARIN IG for Blue Button carin-bb [https://api-dmdh-f31.safhir.io/v1/api/carin-bb/metadata(https://api-dmdh-f31.safhir.io/v1/api/carin-bb/metadata)
Da Vinci Payer Data Exchange pdex https://api-dmdh-f31.safhir.io/v1/api/pdex/metadata
HL7 FHIR® US Core uscore Resources included in PDex
https://api-dmdh-f31.safhir.io/v1/api/uscore/metadata
DaVinci PDex US Drug Formulary formulary https://api-dmdh-f31.safhir.io/v1/api/secure-formulary/metadata
DaVinci PDex Plan Net plannet https://api-dmdh-f31.safhir.io/v1/api/plannet/metadata

When working with different client instances of SAFHIR the content of the capability statements will be the same with just the [base_url] value changing to point to a different environment.

Swagger Files

The SAFHIR platform creates OpenAPI.json files, frequently referred to as swagger files from the Capability Statements provided. The swagger files enable developers to better understand the server interactions.

Swagger files are available for download using the same endpoint conventions as for capability statements. Therefore if a capabilitystatement is at:

  • [base_url][/ig_name]/metadata

The openapi.json file will be found at:

  • [base_url][/ig_name]/openapi.json

SAFHIR also provides a swagger UI for each openapi.json file. the links for the appropriate IGs are as follows:

Implementation Guide IG Short Name Swagger UI Link
CARIN IG for Blue Button carin-bb https://api-dmdh-ut1.safhir.io/v1/apidocs//carin-bb
Da Vinci Payer Data Exchange pdex https://api-dmdh-ut1.safhir.io/v1/apidocs/pdex
HL7 FHIR® US Core uscore Resources included in PDex
https://api-dmdh-f31.safhir.io/v1/api/docs/uscore
DaVinci PDex US Drug Formulary formulary https://api-dmdh-f31.safhir.io/v1/api/docs/secure-formulary
DaVinci PDex Plan Net plannet https://api-dmdh-f31.safhir.io/v1/api/docs/plannet

Postman Collections

Postman is a popular API tool used by Developers. The SAFHIR Development team have provided a set of Postman collections to accelerate development of apps that use the FHIR APIs published by the SAFHIR platform.

Implementation Guide IG Short Name Postman Collection Link
CARIN IG for Blue Button carin-bb __ CARIN BlueButton IG APIs
Da Vinci Payer Data Exchange pdex __ PDEX IG APIs
HL7 FHIR® US Core uscore Resources included in PDex
US Core Server CapabilityStatement
DaVinci PDex US Drug Formulary formulary __ Drug Formulary IG (Open-Access) APIs
DaVinci PDex Plan Net plannet __ PlanNet IG (Open-Access) IG APIs