Healthcare is one of the last industries where critical financial workflows still run on spreadsheets, manual lookups, and siloed vendor tools stitched together with duct tape.
We decided to fix that.
At VBC Risk Analytics, we built the Precise Health Risk Compass™ — a platform that exposes every critical risk adjustment workflow through a unified healthcare apis layer. REST architecture, JSON responses, API key auth, 99.9% uptime SLA.
This post walks through what we built, how the endpoints work, and the technical decisions behind them.
The Problem We're Solving
Medicare Advantage plans get paid based on the risk profile of their members. That risk profile depends on accurate diagnosis coding, provider verification, and compliance validation — all of which need to happen fast, at scale, and without manual bottlenecks.
Most organizations handle this with:
- Manual RAF score calculations in Excel
- One-off vendor integrations for NPI lookups
- Separate tools for coding validation, audit prep, and compliance checks
Each tool has its own auth model, data format, and failure modes. Integration is painful. Maintenance is worse.
We built six healthcare apis on one platform to replace all of it.
The API Suite: Six Endpoints, One Architecture
Every endpoint shares:
- REST architecture with standard HTTP methods
- JSON request/response format
- API key authentication via header
- Consistent error handling with structured error objects
- 99.9% uptime SLA
- HIPAA compliant infrastructure, ISO 27001:2022 certified
Here's what each one does.
1. RAF Score API — Real-Time Risk Scoring
What it does: Calculates CMS-HCC risk adjustment factor scores for individual patients at the point of care.
Endpoint behavior:
- Accepts patient demographics + diagnosis codes
- Returns blended RAF scores across V24, V28, ESRD, and RxHCC models
- Includes care gap analysis comparing historical conditions against current year
- Response time optimized for clinical workflow integration
curl -X 'POST' \
'https://restapi.npidataservices.com/raf/api/v1/getScore' \
-H 'accept: application/json' \
-H 'ApiKey: ' \
-H 'Content-Type: application/json' \
-d '{
"model": "CMS-HCC-V24 Continuing Enrollee",
"factor": "Community NonDual Aged",
"age": 66,
"gender": "MALE",
"HCC_Codes": [
"E119", "C61", "N1832", "I509","J449"
]
}'
Why it matters: Organizations using the raf score api have seen a 90% reduction in risk calculation time vs. manual methods. When a provider is mid-encounter, they need a score in milliseconds not after a batch job runs overnight.
2. RAF Batch API — Population-Scale Processing
What it does: Processes up to 100,000 records in a single batch for population-level risk analysis.
How it works:
- Submit a CSV file via the API
- Receive a job ID
- Poll job status endpoint
- Download results through a secure AWS S3 signed URL
curl -X 'POST' \
'https://www.vbcriskanalytics.com/raf-batch-api/getPreProspectScore' \
-H 'accept: /' \
-H 'ApiKey: your_api_key' \
-H 'Content-Type: multipart/form-data' \
-H 'X-CSRF-TOKEN: ' \
-F 'risk_model=CMS-HCC-V28 Continuing Enrollee' \
-F 'risk_factor=Community NonDual Aged' \
-F 'file=@input_pre_prospective.csv;type=text/csv'
Use cases:
- Pre-audit and post-audit RAF analysis
- Medicare overpayment identification
- Missed opportunity detection across entire member populations
- Submission deadline population sweeps
Design decision: We went with async processing + S3 signed URLs instead of streaming results back. At 100K records, streaming creates timeout and memory pressure issues. The S3 approach lets clients download results at their own pace with secure, time-limited URLs.
3. ICD-10 Guideline Auditor API — Automated Coding Validation
What it does: Validates diagnosis codes against 14+ CMS coding rules before submission.
Validation rules include:
- Excludes1 / Excludes2 conflict detection
- Laterality validation
- Manifestation/etiology pair checking
- Age and sex conflict detection
- Code specificity enforcement
- Primary diagnosis sequencing rules
curl -X 'POST' \
'https://restapi.vbcriskanalytics.com/code-auditor/api/validate' \
-H 'accept: application/json' \
-H 'APIKey: your_api_key' \
-H 'Content-Type: application/json' \
-d '{
"gender": "female",
"dos_year": 2026,
"ICDs": {
"encounter1": [
"F302", "F202", "R180", "G40111", "D649", "G702"
],
"encounter2": [
"N184", "M869", "B180", "B189", "Z9716", "Z9713", "A4151"
]
}
}'
What makes it different: Every validation detects coding conflicts, validate laterality and sequencing, and reduce denials with real-time CMS guideline enforcement. This perspective catches issues that single-view auditors miss.
Result: Organizations using the icd10 guideline api have achieved up to 80% reduction in coding-related claim denials.
4. ICD-10 Code Lookup API — Medical Coding Intelligence
What it does: Provides instant access to 100,000+ diagnostic codes with rich metadata.
Returns:
- Full code descriptions and hierarchy
- HCC mappings with V24 and V28 coefficient values
- Drug classification tables
- Neoplasm code lookups
- Intelligent fuzzy search for partial or misspelled queries
curl -X 'GET' \
'https://restapi.npidataservices.com/icd10/api/v1/getICD10Details?diag_code=E119' \
-H 'accept: application/json' \
-H 'ApiKey: your_api_key'
Design decision: We added fuzzy search because real-world coding queries are messy. Providers type partial terms, abbreviations, misspellings. A strict lookup returns nothing. Fuzzy matching with relevance scoring returns what they actually need.
5. NPI Lookup API — Provider Verification
What it does: Real-time access to 5 million+ healthcare providers through seven flexible search methods.
Search by:
- NPI number (direct lookup)
- Individual provider name
- Organization name
- PAC ID
- Enrollment ID
- Taxonomy code
- Geographic location (city/state/zip)
curl -X 'GET' \
'https://restapi.npidataservices.com/api/v1/findbyNPIId?NPI=1234455666' \
-H 'accept: application/json' \
-H 'ApiKey: your_api_key'
Response includes:
- Credentials and specialties
- Taxonomy codes
- Multiple practice locations
- PECOS enrollment status
- Medicare participation details
Why we built it: Credentialing delays and stale provider data create downstream problems across billing, referral networks, and audit submissions. The npi lookup api eliminates the need to maintain a separate provider database. Query once, get current data, move on.
6. RADV Scrubber API — Pre-Submission Compliance
**What it does: **Validates encounter data and chart review records before CMS submission using 20+ validation rule-sets.
Coverage:
- 7,000+ HCC-associated ICD codes
- 60+ condition groups aligned with CMS RADV focus areas
- 20+ high-risk validation rules
Flags:
- Unsupported diagnoses
- Missing provider specialties
- Mutually exclusive diagnosis pairs
- Demographic inconsistencies
Each flag includes specific remediation steps so coding team can resolve issues before they reach CMS.
curl -X 'POST' \
'https://restapi.radvscrubber.com/scrubClaims' \
-H 'accept: application/json' \
-H 'APIKey: your_api_key' \
-H 'Content-Type: application/json' \
-d 'curl -X '\''POST'\'' \
'\''https://restapi.radvscrubber.com/pullClaims'\'' \
-H '\''accept: application/json'\'' \
-H '\''APIKey: your_api_key'\'' \
-H '\''Content-Type: application/json'\'' \
-d '\''{
"MemberID": [
{
"member_id": "MBR6Y2P8I",
"icd_codes": [
{
"icd": "A327",
"fromDOS": "2024-04-07",
"toDOS": "2024-04-12"
},
{
"icd": "E133312",
"fromDOS": "2024-01-28",
"toDOS": "2024-01-28"
},
{
"icd": "I4721",
"fromDOS": "2024-02-15",
"toDOS": "2024-02-15"
}
],
"valCondition": false
}
]
}
The math is simple: The cost of catching a RADV Audit discrepancy before submission is a fraction of the penalty for missing it after.
Architecture Decisions Worth Sharing
A few technical choices we made that might be useful if you're building in healthcare:
Unified auth model. One API key across all six endpoints. Healthcare orgs already manage too many credentials. Adding six more per vendor would be a non-starter.
JSON everywhere. Healthcare loves HL7 and X12. We don't. For API-first integrations, JSON is what developers actually want to work with. We handle format translation on our side.
Async for batch, sync for real-time. The RAF Score API and NPI Lookup need sub-second responses — they're called during live clinical encounters. The Batch API and RADV Scrubber process thousands of records and return results asynchronously. Mixing these patterns in one platform required careful queue management but it matches how the workflows actually operate.
Dual scoring on the auditor. Returning both provider and payer perspectives from the ICD-10 auditor was a late addition that turned out to be one of the most valued features. The same code set looks different depending on which side of the claim you're on.
HIPAA + ISO 27001:2022. Non-negotiable in healthcare. Every endpoint, every data store, every log. If you're building healthcare APIs and you're not starting with compliance architecture, you'll end up rebuilding later.
Getting Started
All six APIs are available with free trials. REST architecture. JSON format. Standard API key auth.
If you're building healthcare tools — EHR integrations, billing platforms, analytics dashboards, population health systems — and you need risk adjustment intelligence baked in, check out the full suite:
Or reach out directly:
Built by VBC Risk Analytics | Troy, Michigan
Questions about the architecture or implementation? Drop them in the comments — happy to go deeper on any of the endpoints.
Top comments (1)
Which of these six API capabilities would save your team the most time right now — real-time RAF scoring, batch population analysis, coding validation, NPI lookup, or pre-submission RADV checks? Building in healthcare is a different beast and I'm curious what other devs are running into.