Query the CMS Blue Button 2.0 FHIR API to retrieve a Medicare beneficiary's ExplanationOfBenefit resources and extract claims history

Steps

1. Register your application on the Blue Button 2.0 developer portal; obtain client ID and secret for the OAuth2 authorization code flow; configure your redirect URI and request the 'patient/ExplanationOfBenefit.read' and 'patient/Patient.read' scopes
2. Initiate the OAuth2 authorization code flow: redirect the beneficiary to the Blue Button authorization endpoint with your client ID, requested scopes, state parameter, and PKCE code challenge; handle the callback to exchange the authorization code for an access token using YOUR_TOKEN
3. GET the beneficiary's Patient resource to confirm identity and retrieve the FHIR patient ID; then GET ExplanationOfBenefit resources with a search by patient: GET /v2/fhir/ExplanationOfBenefit?patient={patient_id}&_count=50
4. Paginate through Bundle.link[rel='next'] links to retrieve the full claims history; Blue Button returns Part A (inpatient), Part B (outpatient and professional), and Part D (drug) claims as distinct ExplanationOfBenefit profiles — distinguish by ExplanationOfBenefit.type coding
5. For each EOB parse: EOB.item for service lines with procedureSequence, productOrService (CPT/HCPCS/NDC), adjudication amounts (submitted, allowed, paid, patient liability); EOB.payment for total claim payment; EOB.diagnosis for ICD-10 codes
6. Store the access token securely; Blue Button tokens have an expiration — implement refresh token logic to maintain access across multi-step workflows without requiring the beneficiary to re-authorize