RAF Batch API: How to Process 100K+ Members Overnight

Why Batch Scoring Matters

A RAF batch API is a programmatic interface that accepts structured population-level input files containing member demographics and diagnosis codes, processes them through the CMS-HCC risk adjustment model simultaneously, and returns complete RAF scores for thousands or hundreds of thousands of members in a single automated overnight run — replacing manual one-by-one calculations at enterprise scale.

A RAF batch API enables organizations to process population-level risk scores at the scale modern risk adjustment demands. Medicare Advantage plans and risk-bearing provider organizations manage populations measured in tens or hundreds of thousands of members. Each member carries a RAF score that must be calculated, validated, and tracked over time. Doing this one member at a time is not operationally viable at population scale.

Batch RAF scoring solves the volume problem by processing entire population files in a single automated run. Instead of 100,000 individual calculations requiring manual input and review, the organization submits a structured data file and receives comprehensive scored results — typically overnight. This shift from individual to population-level processing is what enables risk adjustment to function as an operational discipline rather than an ad-hoc analytical exercise.

The stakes are significant. A plan with 100,000 members and an average RAF score of 1.05 generates approximately $1.09 billion in annual CMS capitation. A systematic 0.05 understatement across the population — easily caused by incomplete diagnosis data in the scoring input — represents roughly $52 million in unrealized revenue. Batch scoring with complete, validated data is the mechanism that catches these population-wide gaps.

How Batch RAF Processing Works

Batch RAF scoring follows a structured pipeline from data ingestion to result delivery. Understanding each stage helps organizations optimize their process and troubleshoot issues when results are unexpected.

• Data Ingestion: The organization submits a structured file — typically CSV or JSON — containing member demographics and associated ICD-10 diagnosis codes. Each record represents one member with their complete diagnosis profile for the measurement period.
• Validation Layer: Before processing, the system validates every record. Invalid ICD-10 codes, missing demographic fields, duplicate member records, and format errors are flagged and reported. Records that pass validation proceed to scoring; failed records are returned with error codes for correction.
• ICD-10 to HCC Mapping: Each member's diagnosis codes are mapped to CMS-HCC V28 Hierarchical Condition Categories using the official CMS crosswalk. The hierarchy logic ensures that within each disease family, only the highest-severity qualifying HCC is retained.
• Score Calculation: The CMS-HCC model applies demographic baselines, HCC coefficients, and disease interaction factors to produce the RAF score for each member. Normalization factors are applied for budget neutrality per CMS specifications.
• Enrichment: Advanced batch platforms augment the raw RAF score with additional analytics — HCC-level detail, year-over-year comparisons, care gap flags, and revenue impact calculations — transforming a simple score into actionable intelligence.
• Result Delivery: Scored results are returned in the same structured format as the input, with additional columns for RAF scores, HCC details, and enrichment data. Results are available for download or delivered directly to downstream systems via API callback or file transfer.

Use Cases for Batch Scoring

Batch RAF scoring serves multiple operational functions across payer and provider organizations. The common thread is the need to score an entire population — or a significant segment — in a single coordinated run.

• Pre-Submission Validation: Before submitting encounter data to CMS, plans run their entire submission file through batch scoring to identify members with unexpected RAF scores — either suspiciously high (potential RADV risk) or suspiciously low (potential revenue leakage). This is the last quality checkpoint before data reaches CMS.
• Revenue Forecasting: Finance and actuarial teams use batch-scored population data to project CMS capitation revenue for upcoming payment periods. Monthly batch runs track how risk scores are trending relative to budget assumptions, enabling mid-year course corrections.
• HCC Recapture Campaigns: Batch scoring with prior-year comparison identifies members whose chronic conditions have not yet been recaptured in the current measurement period. These lists drive targeted provider outreach and Annual Wellness Visit scheduling.
• Network Performance Analysis: Scoring members by attributed provider reveals which providers and practice sites have the highest and lowest HCC capture rates. This provider-level intelligence drives targeted education and CDI program deployment.
• Merger and Acquisition Due Diligence: When evaluating an acquisition target, batch scoring the target's membership reveals true population risk profile, documentation quality, and revenue accuracy — critical inputs for valuation and integration planning.
• Regulatory Reporting: Batch scoring supports CMS reporting requirements including the annual risk adjustment reconciliation process and supports automated risk adjustment workflows that depend on population-level scoring data.

Data Preparation and Input Formats

The quality of batch scoring results is directly determined by the quality of input data. Garbage in, garbage out applies with particular force when scoring 100,000 members because data quality issues that affect 1 percent of records still impact 1,000 members.

• Member Demographics: Each record requires date of birth (for age calculation), sex, Medicaid dual-eligibility status, community vs. institutional setting, original reason for Medicare entitlement, and enrollment segment. Missing or incorrect demographics produce incorrect baseline scores before any diagnosis codes are even considered.
• Diagnosis Code Completeness: Include all ICD-10 diagnosis codes from all qualifying encounters during the measurement period — not just the most recent encounter. A member with 15 office visits may have relevant diagnoses documented across multiple encounters that together build the complete HCC profile.
• Code Format Standards: ICD-10 codes must be formatted without decimals (E1165 not E11.65) and must be valid codes in the active CMS code set for the measurement year. Inactive or truncated codes will fail validation and produce incomplete RAF scores.
• Deduplication: Submit one record per member with all diagnosis codes consolidated. Duplicate member records can produce inflated population-level statistics even if individual scores are correct. Deduplication logic should match on member ID, not on name or date of birth alone.
• Date-of-Service Filtering: Only include diagnosis codes from encounters with dates of service within the CMS-defined measurement period. Diagnoses from outside the measurement window do not contribute to the payment year RAF score and can inflate expected revenue projections.
• Provider Attribution: Including the rendering provider NPI with each diagnosis code enables provider-level analysis of batch results — identifying which providers contribute the most and least to population HCC capture.

Processing at Scale

Scaling from 10,000 to 100,000 to 500,000 members introduces technical considerations that organizations should understand when selecting a batch scoring platform.

• Throughput Requirements: A 100,000-member batch with an average of 8 diagnosis codes per member generates 800,000 individual ICD-10 to HCC mappings. The platform must handle this volume within the overnight processing window without degrading accuracy or dropping records.
• Error Isolation: At scale, some records will inevitably contain errors. The platform must process valid records while isolating errors — not fail the entire batch because 50 records out of 100,000 have invalid diagnosis codes. Partial completion with error reporting is essential.
• Idempotency: If a batch run is interrupted and resubmitted, the results must be identical. Batch scoring systems must be idempotent — producing the same output for the same input regardless of how many times the batch is executed.
• Version Consistency: Every record in a single batch must be scored using the same CMS-HCC model version and the same coefficient tables. Mixed-version scoring within a batch produces incomparable results that corrupt downstream analysis.
• Security and Compliance: Batch files contain PHI — member demographics and diagnosis codes. The platform must support encryption in transit and at rest, access controls, and audit logging that meets HIPAA requirements. File transfer protocols should use SFTP or encrypted API endpoints, never unencrypted email or FTP.
• Result Archival: Organizations should archive batch input files and scored results for every run. This creates a longitudinal record of population risk that supports trend analysis, audit defense, and regulatory inquiries. Building a risk adjustment analytics program requires this historical foundation.

Analyzing Batch Results

The value of batch scoring is realized in the analysis — not in the raw scores themselves. Turning 100,000 individual RAF scores into actionable organizational intelligence requires structured analysis at multiple levels.

• Population Summary Statistics: Start with aggregate metrics: average RAF, median RAF, standard deviation, and the distribution across risk tiers. Compare these metrics to prior periods to identify population-level risk trends — is the population getting sicker, healthier, or simply better documented?
• Year-over-Year Member Comparison: For members present in both current and prior-year batches, calculate the RAF delta. Members with significant decreases may have dropped chronic HCCs that were not recaptured. Members with significant increases should be reviewed for documentation accuracy.
• HCC Gap Analysis: Aggregate HCC-level data across the population to identify which condition categories have the lowest capture rates relative to clinical expectations. If only 40 percent of members with diabetes medications have a diabetes HCC captured, there is a systematic documentation gap. A structured tool comparison can help determine the best approach to closing these gaps.
• Provider Attribution Analysis: Score results grouped by attributed provider reveal documentation performance variation across your network. Providers in the bottom quartile of HCC capture rates are the highest-impact targets for CDI intervention and education.
• Revenue Impact Quantification: Convert RAF score gaps to dollar amounts using the county base rate and coding intensity adjustment. This translates abstract documentation gaps into concrete revenue figures that justify investment in documentation improvement programs.
• Trend Monitoring: Run batch scoring on a regular cadence — monthly or quarterly — and track population metrics over time. Consistent tracking reveals whether documentation improvement initiatives are producing measurable RAF increases and whether those increases are sustainable.