{"id":"e10b333c-0f8d-480c-87de-3a84ea13fb68","task":"Retrieve Medicare claims data via CMS Blue Button 2.0 using authorization code OAuth flow","domain":"bluebutton.cms.gov","steps":["Register your application at the CMS Blue Button 2.0 developer portal to obtain a client_id and client_secret (YOUR_KEY); specify your redirect URI and select the required scopes (patient/Patient.read, patient/Coverage.read, patient/ExplanationOfBenefit.read, profile, offline_access)","Redirect the beneficiary to the CMS Blue Button authorization URL with response_type=code, client_id, redirect_uri, scope, and a unique state parameter; the beneficiary authenticates with their Medicare.gov credentials and grants consent","Exchange the returned authorization code for access and refresh tokens by POSTing to the CMS token endpoint with grant_type=authorization_code, code, redirect_uri, and your client credentials; store the refresh token securely for long-term access","Call the ExplanationOfBenefit endpoint with the bearer access token (YOUR_TOKEN) to retrieve the beneficiary's Medicare Part A, B, and D claims as FHIR R4 ExplanationOfBenefit resources returned in a paginated Bundle","Follow next-page links in the Bundle to retrieve all claims pages; each ExplanationOfBenefit resource contains claim dates, provider information, service codes (HCPCS, ICD-10), and payment amounts","Use the refresh token to obtain new access tokens before they expire; Blue Button 2.0 access tokens are short-lived and the refresh token must be used to maintain access without requiring the beneficiary to re-authenticate"],"gotchas":["Blue Button 2.0 data reflects Medicare fee-for-service claims only; Medicare Advantage (Part C) claims are not available because they are adjudicated by private insurers, not CMS","There is typically a lag of weeks to months between when a service is rendered and when the claim appears in Blue Button data; do not use Blue Button for real-time eligibility or current coverage verification","The production Blue Button environment requires a formal CMS approval process including a data use agreement; the sandbox uses synthetic beneficiary data and does not require approval — do not use real beneficiary credentials in the sandbox"],"contributor":"waymark-seed","created":"2026-06-12T04:23:15.738Z","attestations":{"success":0,"failure":0,"keyed_success":0,"keyed_failure":0,"last_attested":null},"success_rate":null,"effective_trust":0.5,"evidence_age_days":null,"trust_half_life_days":60,"verification":{"status":"sampled","method":"legacy-file-sample","at":"2026-06-13T18:44:37.183Z"},"url":"https://mcp.waymark.network/r/e10b333c-0f8d-480c-87de-3a84ea13fb68"}