RAF Score API: Top Use Cases for Health Plans and Developers

What the RAF Score API Does

A RAF score API is a programmatic interface that accepts patient demographic and diagnosis data, applies CMS-HCC risk adjustment model logic — including ICD-10-to-HCC mapping, hierarchy rules, disease interaction factors, and normalization — and returns calculated Risk Adjustment Factor scores in real time, enabling health plans and developers to embed accurate risk intelligence directly into clinical and operational workflows.

The RAF Score API provides programmatic access to CMS-HCC risk adjustment calculations through standard REST endpoints. Instead of building and maintaining internal RAF calculation engines — which require ongoing updates for model changes, coefficient revisions, and ICD-10 mapping modifications — organizations call the API with patient data and receive calculated RAF scores, HCC mappings, and care gap analysis in real time.

The API handles the complexity of RAF score calculation: ICD-10-to-HCC mapping under V28, hierarchy application across 26 disease families, coefficient assignment, disease interaction calculations, and normalization. Member RAF scores in a typical Medicare Advantage plan range from approximately 0.2 for the healthiest members to 4.0 or higher for the most complex, and each 0.1 increment in a plan's average RAF score translates to roughly $80–$120 in annual per-member revenue. This abstraction layer means development teams can focus on building applications that use risk intelligence rather than replicating CMS calculation logic.

Use Case 1: Real-Time Risk Scoring at Point of Care

The highest-value use case for the RAF Score API is embedding real-time risk intelligence directly into clinical workflows. When a provider opens a patient chart, the API calculates the current RAF score based on documented conditions and identifies gaps — before the encounter begins.

• Pre-Visit Preparation: Schedulers or care coordinators trigger an API call when appointments are confirmed. The response includes the member's current RAF score, active HCCs, and suspect conditions that should be evaluated during the visit. This pre-visit intelligence ensures providers are prepared to address risk-relevant conditions.
• During-Visit Alerts: EHR integrations call the API as providers document diagnoses in real time. The API returns updated RAF calculations and identifies whether new diagnoses map to HCCs, giving providers immediate feedback on the risk adjustment impact of their documentation.
• Post-Visit Validation: After the encounter, the API validates submitted diagnosis codes against V28 mapping tables and flags codes that do not map to HCCs, codes that may be missing specificity, or documentation patterns that suggest additional conditions should have been addressed.
• Annual Wellness Visit Optimization: AWVs integrated with the RAF Score API achieve significantly higher HCC recapture rates — typically 15–25 percentage points above baseline — because providers see exactly which chronic conditions need re-documentation before the visit begins. Plans with typical HCC recapture rates of 65–75% have reported improvements to 85–90% after deploying point-of-care risk alerts.

Use Case 2: Population-Level Batch Processing

Health plans managing tens or hundreds of thousands of Medicare Advantage members — nationally, Medicare Advantage enrollment exceeds 35 million beneficiaries across plans typically ranging from 50,000 to 500,000 members — need population-level risk intelligence for revenue forecasting, gap prioritization, and strategic planning. The batch API endpoint processes entire member populations in a single request.

• Revenue Forecasting: Submit all member records with current diagnosis data to calculate population-level RAF scores. Compare against CMS MOR data to identify aggregate underpayment or overpayment exposure — plans commonly identify 3–8% RAF score gaps between submitted and supportable scores. Plans use this analysis for budget planning, bid development, and financial reporting.
• Quarterly Risk Reviews: Run batch calculations quarterly to track RAF score trends across the population. Identify segments where scores are declining (indicating recapture failures) or increasing unexpectedly (indicating potential accuracy concerns that warrant review).
• Provider Performance Analysis: Aggregate batch results by attributed provider to identify which practices generate the most accurate RAF scores, which have the highest gap rates, and which need targeted education and support.
• New Member Onboarding: When new members enroll, batch-process their available claims history to generate initial RAF estimates. This establishes baseline risk profiles before the first encounter and helps prioritize outreach for members with suspected high complexity.
• Year-Over-Year Comparison: The API supports multiple model versions, enabling side-by-side comparison of V24 and V28 RAF scores for the same population — critical for understanding the revenue impact of the model transition.

Use Case 3: Care Gap Identification

The RAF Score API does not just calculate scores — it identifies the specific conditions and coding gaps that represent the difference between the member's current RAF score and their expected RAF score based on clinical history. Across the Medicare Advantage market, approximately 20–30% of clinically supported HCCs go uncaptured in any given plan year, representing substantial revenue and quality-of-care risk.

• HCC Recapture Gaps: The API compares current-year documented HCCs against prior-year active HCCs to identify chronic conditions that have not been recaptured. Each gap includes the specific HCC, its coefficient value, and the revenue impact of non-recapture.
• Suspect Condition Identification: Using pharmacy claims, lab results, and diagnostic history, the API generates suspect condition lists — conditions the member likely has based on treatment patterns but that have not been documented as active diagnoses in the current year.
• Specificity Gaps: The API identifies diagnosis codes that were submitted at insufficient specificity to map to HCCs under V28. For example, an unspecified diabetes code that does not trigger an HCC when a more specific code (supported by the same documentation) would qualify.
• Revenue Prioritization: Gap results are sorted by potential revenue impact, enabling care coordinators and coding teams to focus outreach on members and conditions with the highest return — not just the highest volume of gaps.

Use Case 4: Pre-Audit Risk Validation

With RADV audit scope and frequency increasing — CMS RADV error rates across the industry typically range from 5–15% of audited HCCs, with financial recoveries that can reach millions of dollars per contract — health plans use the RAF Score API to simulate audit outcomes against their submitted data before CMS comes calling.

• Documentation Sufficiency Scoring: The API evaluates submitted HCCs against documentation standards and assigns a confidence score indicating the likelihood each HCC would survive RADV validation. HCCs with low confidence scores are flagged for proactive medical record review.
• Extrapolation Risk Modeling: By identifying the percentage of submitted HCCs likely to fail validation, plans can model the potential financial impact of RADV extrapolation — converting abstract audit risk into concrete dollar exposure.
• Targeted Remediation: Pre-audit validation results identify specific members and HCCs that need documentation strengthening. Plans can conduct targeted chart reviews and provider outreach to shore up documentation before audit selection occurs.
• Contract-Level Risk Assessment: Aggregate pre-audit scores across all members in a CMS contract to identify which contracts carry the highest RADV exposure. This contract-level view helps compliance teams allocate audit preparation resources effectively.

Use Case 5: Developer Integration

The RAF Score API is designed for developers building healthcare applications that need embedded risk intelligence — from EHR plugins to population health platforms to custom analytics dashboards.

• Standard REST Architecture: The API uses standard REST conventions with JSON request and response payloads. Any development team with HTTP client experience can integrate within days, not weeks — typical integration timelines run 3–10 business days from API key issuance to first production call.
• Comprehensive Documentation: Interactive API documentation with request/response examples, error handling guides, and code samples in Python, JavaScript, Java, and C# reduce integration friction and accelerate time-to-production.
• Sandbox Environment: A dedicated sandbox with synthetic patient data enables developers to test integrations without PHI exposure. The sandbox mirrors production behavior exactly, ensuring that code tested in sandbox works identically in production.
• Webhook Support: For asynchronous workflows, the API supports webhook callbacks that notify your application when batch processing completes or when specific risk thresholds are triggered — eliminating the need for polling.
• Rate Limiting and SLAs: Published rate limits and uptime SLAs ensure developers can build production applications with confidence. The API supports both development-tier (rate-limited, free) and production-tier (high-throughput, SLA-backed) access.

Getting Started

Integrating the RAF Score API into your workflow follows a straightforward path from evaluation to production deployment.

• Step 1 — Evaluate: Request API documentation and sandbox access to test against your specific use case. Run sample calculations to verify that results align with your internal RAF models and data requirements.
• Step 2 — Design: Map the API endpoints to your workflow requirements. Determine whether you need real-time scoring, batch processing, or both. Define the integration points in your existing systems where API calls will be triggered.
• Step 3 — Build: Implement the integration using the API documentation and code samples. The sandbox environment supports full end-to-end testing with synthetic data that mirrors production payload structures.
• Step 4 — Validate: Compare API-calculated RAF scores against known benchmarks to ensure accuracy. Test edge cases including members with no HCCs, members with maximum complexity, and members with V28-specific mapping scenarios.
• Step 5 — Deploy: Move to production endpoints with appropriate authentication, monitoring, and error handling in place. The API team provides go-live support to ensure smooth transition from sandbox to production.