Welcome to Day 5 of our Fall 2025 Launch Week! Missed Day 4? Read about Day 4's launch.
Today we're excited to make public and freely available the reference documentation and guides we've developed internally to understand the diversity of payer data. When you look at claims data in the FHIR Explanation of Benefit (EOB) resource, the journey from origin schemas like CMS 1500, CMS 1450, UB04 claims, or NCPDP pharmacy transactions requires deep research and in-depth understanding. We built these resources to support ourselves. Now they're available for free at Flexpa Docs.
What We're Releasing
Two comprehensive resources designed to make working with claims data significantly easier:
-
Claims Data Guide - A broad introduction covering what's in claims data, how it's coded, and how to approach it from a health informatics perspective. Think of it as "Medical Coding 101" for developers.
-
CARIN Blue Button EOB Reference Documentation - Detailed reference covering the most common 80% of elements in the CARIN BB profiled Explanation of Benefit resource, with practical examples from real-world payer implementations.
These complement the official HL7 CARIN Blue Button Implementation Guide with practical, example-driven documentation grounded in what we've learned from connecting to over 300 payer endpoints.
Why Claims Data Matters
Claims data powers an enormous range of healthcare applications: care coordination, cost transparency, population health analytics, quality measurement, clinical trial matching, and legal record retrieval. At Flexpa, we've worked with all these use cases and more.
Claims provide a rich longitudinal perspective on patients. Often, you can answer clinical or operational questions just by correctly interpreting claims data. But understanding what's actually in this data—and how it maps from billing forms to standardized FHIR resources—requires navigating specialized terminology, complex code systems, and implementation quirks that vary across payers.
The HL7 CARIN Blue Button Implementation Guide is the normative standard, but like all HL7 IGs, it uses specialized vocabulary and can be difficult to navigate for developers new to healthcare data. Our documentation helps by showing exactly where value sets, bindings, and elements appear in practice, with examples from real payer data.
The Claims Data Guide: From Billing Forms to FHIR
Our Claims Data Guide walks through the complete lifecycle of claims data, using patient stories to illustrate how coded medical events become structured data.
Take Sarah's story: She visits Dr. Martinez for a 45-minute annual physical, discusses health goals, and gets routine lab work ordered. That visit generates a professional claim with a CPT code (a HCPCS Level I code describing the service), an ICD-10 diagnosis code, place-of-service code, and over 30 other fields capturing every detail—the provider's NPI, service date, submitted charges.
The doctor's office submits the claim for $350. The payer processes it: checking in-network status, applying deductibles, adjudicating covered amounts. That claim joins millions of others in datasets used for population health studies, quality measures, and care coordination.
This straightforward example shows the timeline and coded events behind every claim—something that happens hundreds of thousands of times daily across the healthcare system. The guide shows how these events are represented in claims, how the different claim types (institutional, professional, pharmacy) differ, and what codes appear in each.
From there, it connects to the FHIR Explanation of Benefit resource. Where would you find that CPT code in the EOB? What about the place-of-service? One of the first questions developers ask about CARIN BB data is "Does it have CPT codes?" Our guide answers these questions with clear mappings and examples.
CARIN Blue Button Reference Documentation: The Dictionary You Need
The second part of today's release is brand-new reference documentation for the CARIN BB Explanation of Benefit, built from scratch based on our experience with over 300 payer connections.
The documentation breaks down the EOB into three primary claim types:
Institutional Claims (inpatient and outpatient) - Covers type-of-bill codes, DRGs (Diagnosis Related Groups), revenue center codes, present-on-admission indicators, and how these map from CMS 1450 (UB04) forms to FHIR. We explain nuances like the difference between inpatient facility claims and outpatient facility claims, and how value sets are actually used in practice.
Professional Claims - Details place-of-service codes, CPT/HCPCS procedure codes, diagnosis pointers, and the structure of professional claims from individual practitioners or clinics. Maps from CMS 1500 forms to the EOB structure.
Pharmacy Claims - Explains NDC codes, days supply, refill numbers, DAW (Dispense as Written) codes, formulary indicators, and pharmacy-specific elements from NCPDP transactions.
For each claim type, we outline key terminologies and codable concepts with examples, code systems, and rewritten (non-normative) narratives explaining how these elements are used in the real world. This is effectively a dictionary that complements the official HL7 implementation guide—practical, example-driven, and grounded in what payers actually return.
Who This Is For
This reference documentation is designed for anyone consuming CARIN Blue Button profiled claims data today—whether from CMS-9115-F Patient Access APIs or preparing for CMS-0057 payer-to-payer exchange. If you're building with claims data from health plans, you'll find answers to practical questions:
- How do I find procedure codes in an institutional EOB?
- What's the difference between adjudication categories?
- Where are medication names in pharmacy claims?
- How do I interpret diagnosis codes and their relationships to procedures?
- What code systems should I expect for different claim types?
Flexpa has built the reference documentation we wish had existed when we started. We're making it public because claims data should be more accessible, and understanding it shouldn't require reverse-engineering hundreds of payer implementations.
Explore the Documentation
Start with the Claims Data Guide for foundational concepts, then dive into the CARIN BB EOB Reference for detailed element-by-element documentation.
These resources are living documents. As we continue working with payer data and uncovering new patterns, we'll update them with additional examples and clarifications.
Building healthcare applications? Check out our documentation to start working with patient-consented claims data through Flexpa's API, or contact us to learn more.
Interested in staying updated on Flexpa's latest features and industry developments? Subscribe to our newsletter. Ready to start building? Schedule a demo to learn more.
