FHIR APIs for Interoperability
The Excellus BlueCross BlueShield FHIR APIs for Interoperability enable health plan members to access their healthcare information through authorized third-party applications. The APIs also allow access to public non-member specific information such as Provider and Pharmacy Directories.
The Excellus BlueCross BlueShield FHIR APIs for Interoperability are grouped into two categories of APIs -
- Patient Access APIs
- Public Access APIs
The Patient Access APIs adhere to the OAuth 2.0 (https://oauth.net/2/) protocol for authorization and specifically follows the SMART App Launch Framework (http://www.hl7.org/fhir/smart-app-launch/) for connecting third-party patient apps. Use of the Patient Access APIs requires client application registration and end-user authentication and consent.
The Public Access APIs do not require client application registration and do not require end-user authentication or consent.
FHIR API Discovery
The Excellus BlueCross BlueShield FHIR APIs for Interoperability provides a FHIR-compliant Capability Statement Resource available at
The OAuth register, authorize and token endpoint urls are also discoverable at
Third-party client application registration
The Excellus BlueCross BlueShield FHIR APIs for Interoperability Patient Access APIs require that each third-party client application is registered with the health plan’s authorization service. In order to streamline the client application registration process Excellus BlueCross BlueShield has implemented the OAuth 2.0 Dynamic Client Registration Protocol (https://tools.ietf.org/html/rfc7591) according to SMART on FHIR’s recommendation for client application registration (http://www.hl7.org/fhir/smart-app-launch/#registering-a-smart-app-with-an-ehr)
When registering the client application with the Excellus BlueCross BlueShield FHIR API Authorization Service, it is important to specify the “scopes” (http://hl7.org/fhir/smart-app-launch/1.0.0/scopes-and-launch-context/index.html) that the application requires to function. The scopes that the Patient Access APIs support are
- patient/*.read
- user/*.read
- launch/patient
- offline_access
Dynamic Client Registration will provide a client id (and client secret if the confidential client option was selected during registration). Client id (and client secret if provided) must be used on subsequent authorize and token endpoint url requests.
Client application registration may be revoked by Excellus BlueCross BlueShield if it is shown that an application is behaving in a manner inconsistent with this guide and poses an unacceptable level of risk to the security and stability of the health plan’s systems.
End-user authentication and consent
When the client application has been registered, the application will request authorization in order to gain access to the Patient Access APIs on behalf of the end-user (the health plan member). This is done in accordance with the SMART authorization sequence (http://hl7.org/fhir/smart-app-launch/1.0.0/scopes-and-launch-context/index.html).
The health plan member will be asked to log in using their excellusbcbs.com web login credentials to authenticate and confirm their identity. If the health plan member does not have a excellusbcbs.com web login account or has forgotten their account information, there will be links to take the health plan member to the Member Web Portal to register or request login assistance. Upon successful authentication, the health plan member will be presented with a web screen identifying the name of the application (provided during the third-party client application registration) that is attempting to access their healthcare information and information regarding the scopes of access (http://hl7.org/fhir/smart-app-launch/1.0.0/scopes-and-launch-context/index.html) that the application is requesting. If the health plan member agrees and consents to allow the third-party client application to access their health care information, the third-party client application will be able to request an access token to be used to retrieve the health plan member’s healthcare information from the Patient Access APIs.
A health plan member may choose to revoke client application access to their healthcare information at any time.
Error Responses
The Excellus BlueCross BlueShield FHIR APIs for Interoperability adhere to the FHIR specification guidance regarding the use of specific HTTP status codes regarding particular error states (https://www.hl7.org/fhir/http.html#Status-Codes).
Common HTTP status codes may be returned in many different situations
- 400 Bad Request - The transaction could not be processed as requested
- 401 Not Authorized - Successful authorization is required for the resource requested
- 404 Not Found - Resource type is not supported
- 500 Internal Server Error - An internal server side issue prevented the transaction from completing successfully
Read Operations
A GET for an unknown resource will return an HTTP 404 Not Found status code
Search Operations
A search request that succeeds but has zero search results will return an HTTP 200 OK status code
API Specifications
The Base request URL for all FHIR Resources is
- https://fhir.excellusbcbs.com/fhir/api
FHIR Specification and Profile Conformance
In accordance with the CMS Interoperability and Patient Access Final Rule, the Excellus BlueCross BlueShield FHIR APIs for Interoperability align to the required FHIR Profiles except where system limitations or expected real-world usage scenarios dictated otherwise.
The profiles supported by the Excellus BlueCross BlueShield FHIR APIs for Interoperability are
- The CARIN Consumer Directed Payer Data Exchange IG (also referred to as the CARIN IG for Blue Button®)
- HL7 US Core IG
- HL7 FHIR Da Vinci PDex Plan Net IG
There are some FHIR resources that are detailed in multiple profiles. In those cases the FHIR resource returned by the FHIR APIs will be compliant with all applicable profiles.
Patient Access APIs
Coverage
Read:
[Base]/Coverage/[id]
Search:
Parameter: _id
- The FHIR id of the Coverage record
- [Base]/Coverage?_id=[_id]
Options:
Parameter: _include
- Coverage:payor
- [Base]/Coverage?[search-parameters]&_include=Coverage:payor
ExplanationOfBenefit
Read:
[Base]/ExplanationOfBenefit/[id]
Search:
Parameter: <none>
- Returns all ExplanationOfBenefit records accessible by the logged in user
- [Base]/ExplanationOfBenefit
Parameter: _id
- The FHIR id of the ExplanationOfBenefit record to return
- [Base]/ExplanationOfBenefit?_id=[_id]
Parameter: patient
- The FHIR id of the Patient for the ExplanationOfBenefit records to return
- [Base]/ExplanationOfBenefit?patient=[patient id]
Parameter: service-date
- The service date of the ExplanationOfBenefit records to return
- [Base]/ExplanationOfBenefit?patient=[patient id]
Parameter: type
- The type of ExplanationOfBenefit records to return
- [Base]/ExplanationOfBenefit?type=[type]
Immunization
Read:
[Base]/Immunization/[id]
Search:
Parameter: <none>
- Returns all Immunization records accessible by the logged in user
- [Base]/Immunization
Parameter: _id
- The FHIR id of the Immunization record to return
- [Base]/Immunization?_id=[_id]
Parameter: date
- The date of the Immunization records to return
- [Base]/Immunization?date=[date]
Parameter: patient
- The FHIR id of the Patient for the Immunization records to return
- [Base]/Immunization?patient=[patient id]
Parameter: status
- The status of the Immunization records to return
- [Base]/Immunization?status=[status]
Observation
Read:
[Base]/Observation/[id]
Search:
Parameter: <none>
- Returns all Observation records accessible by the logged in user
- [Base]/Observation
Parameter: _id
- The FHIR id of the Observation record to return
- [Base]/Observation?_id=[_id]
Parameter: category
- The category of the Observation records to return
- [Base]/Observation?category=[category]
Parameter: code
- The code of the Observation records to return
- [Base]/Observation?code=[code]
Parameter: date
- The date of the Observation records to return
- [Base]/Observation?date=[date]
Parameter: patient
- The FHIR id of the Patient for the Observation records to return
- [Base]/Observation?patient=[patient id]
Patient Resource
Read:
[Base]/Patient/[id]
Search:
Parameter: <none>
- Returns all Patient records accessible by the logged in user
- [Base]/Patient
Parameter: _id
- The FHIR id of the Patient record to return
- [Base]/Patient?_id=[_id]
Parameter: birthdate
- The birthdate of the Patient records to return
- [Base]/Patient?birthdate=[birthdate]
Parameter: gender
- The gender of the Patient records to return
- [Base]/Patient?gender=[gender]
Parameter: identifier
- The member identifier of the Patient records to return
- [Base]/Patient?identifier=[identifier]
Parameter: name
- The name of the Patient records to return
- [Base]/Patient?name=[name]
Public Access APIs
HealthcareService
Read:
[Base]/HealthcareService/[id]
InsurancePlan
Read:
[Base]/InsurancePlan/[id]
Search:
Parameter: _id
- The FHIR id of the InsurancePlan record to return
- [Base]/InsurancePlan?_id=[_id]
Location
Read:
[Base]/Location/[id]
Search:
Parameter: _id
- The FHIR id of the Location record to return
- [Base]/Location?_id=[_id]
Parameter: address
- The address of the Location records to return
- [Base]/Location?address=[address]
Organization
Read:
[Base]/Organization/[id]
Search:
Parameter: _id
- The FHIR id of the Organization record to return
- [Base]/Organization?_id=[_id]
OrganizationAffiliation
Read:
[Base]/OrganizationAffiliation/[id]
Practitioner
Notes:
Due to the large volume of Practitioner resources that may be retrieved for certain search criteria, transaction response size is limited to 25 Practitioner records returned per request. Pagination/paging is not supported at this time so if additional results are desired, more specific search criteria must be provided.
Read:
[Base]/Practitioner/[id]
Search:
Parameter: _id
- The FHIR id of the Practitioner record to return
- [Base]/Practitioner?_id=[_id]
Parameter: family
- The family name of the Practitioner records to return
- [Base]/Practitioner?family =[family]
Parameter: given
- The given name of the Practitioner records to return
- [Base]/Practitioner?given =[given]
Parameter: identifier
- The identifier of the Practitioner records to return
- [Base]/Practitioner?identifier=[identifier]
Parameter: name
- The name of the Practitioner records to return
- [Base]/Practitioner?name=[name]
PractitionerRole
Read:
[Base]/PractitionerRole/[id]
Search:
Parameter: _id
- The FHIR id of the PractitionerRole record to return
- [Base]/PractitionerRole?_id=[_id]
Parameter: practitioner
- The FHIR id of the Practitioner for the PractitionerRole records to return
- [Base]/PractitionerRole?practitioner=[practitioner]
Service Level Agreements and Performance
The Excellus BlueCross BlueShield FHIR APIs for Interoperability are intended to be available 24 hours a day, 7 days a week, 365 days a year. However Excellus BlueCross BlueShield does have scheduled system maintenance windows. Transaction requests made during these times may not complete successfully due to planned system downtime. Other planned and unplanned outages will be noted on excellusbcbs.com.
The Excellus BlueCross BlueShield FHIR APIs for Interoperability are designed for rapid retrieval of the requested information from the health plan’s backend systems. Depending on the complexity of the request transaction, the volume of data being retrieved, and the number of backend systems accessed to retrieve the requested information response time of an individual transaction can vary dramatically, therefore performance of individual requests can not be guaranteed. If an individual transaction takes more than sixty (60) seconds, a timeout response will be returned. A client application may reattempt the request preferably with more specific query/search parameters provided to provide a more timely and accurate response.
