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*
- According to the capabilitystatement of the Blue Button API, the “billablePeriodDate” is a searchable parameter for EOB. It is no longer true. In the future release of the document, this parameter will be removed (see https://groups.google.com/forum/#!topic/developer-group-for-cms-blue-button-api/ITZX2–l-sU).
- 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.
- FHIR has defined another search parameter $everything (https://www.hl7.org/fhir/operation-patient-everything.html). Blue Button API may support it in the future, see https://groups.google.com/forum/#!topic/developer-group-for-cms-blue-button-api/zaB6bEgXRhg.
- 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.