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/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/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/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. 

Technical Support 

IE Browser Modal