Test Results of CMS Blue Button 2.0 Sandbox

This blog post describes our initial test results of the CMS Blue Button 2.0 Sandbox 2.0 API. During this API’s test period, we built a web-based solution (https://www.redixbb.com) to allow Medicare beneficiaries to view their claim data. Press this link to view our prototype.

CMS published the Blue Button 2.0 Documentation for developers (https://bluebutton.cms.gov/developers/). The documentation is clear, and developers should be able to follow the documentation to implement a solution. While you are on the site, you should also check the support link to view the discussions and ideas on a certain topic.

This report can be used to help developers save development time. However, if Blue Button API specifications are changed in the future, this report will be revised accordingly.

  • In general, the Blue Button 2.0 API follows the FHIR STU 3 specifications (https://www.hl7.org/fhir/). However, not all of the FHIR specifications are supported. You can check the capability statement defined in the metadata for the Blue Button API (https://sandbox.bluebutton.cms.gov/v1/fhir/metadata). Currently, CMS Blue Button Sandbox supports three resources: Patient, Coverage, and EOB (ExplanationOfBenefit). Vital stats, such as Observation or AllergyIntotelenace are not supported.
  • The CMS authorization endpoint is:

           https://sandbox.bluebutton.cms.gov/v1/o/authorize/

           Note that “/” at the end is important. If you don’t include it, you will get a 404 error.

  • Blue Button Sandbox has 30,000 sample accounts from BBUser00000 to BBUser29999 with the password “PW00000!” to “PW29999!”. Note that the “!” is part of the password.
  • The maximum number of EOB records returned by the Blue Button Sandbox in one API call is 50. One can use “count=nn” to set the number of EOBs , where nn is a number between 1 and 50. Note that the FHIR standard uses “_count” (https://www.hl7.org/fhir/search.html) as a search parameter. In the Blue Button, however, “_count” will be ignored. One has to use “count” (no underscore) in order to set the number of EOBs to be returned.
  • The wildcard search is not supported. For example, the following statement will result in a 404 error.

https://sandbox.bluebutton.cms.gov/v1/fhir/ExplanationOfBenefit/carrier-209*

  • FHIR supports two search parameters, “_include” and “_revinclude”. Users can use these two keywords to query a resource and its referred resources. For example, users can use the _include parameter in patient resource queries to indicate that other resources that refer to the same subject (patient) be included in the results. Both “_include” and “_revinclude” are not supported in Blue Button API.
  • When registering your application on https://sandbox.bluebutton.cms.gov/v1/accounts/mfa/login, you need to define a field “Redirect Uris”. The redirect field must start with “http://”, regardless of the environment. If you only enter “localhost:my_port/my_application_entry_point” for your development environment, it will not work and a “Enter a valid URL” error will be returned. Also, the “Redirect Uris” must be a valid path in your application. If not correctly set, an error “invalid_request: mismatching redirect URI” will be returned.
  • Once an access token is obtained from the Blue Button, the token will be good for the next 36,000 seconds, i.e., 10 hours.
  • Duplicates of ExplanationOfBenefit.id in the sandbox were reported. We are assuming this will not be a problem in production.
  • The math in an EOB does not add up correctly in the sandbox. We are also assuming that this will not be an issue in the production environment.