Forem: Chin Ramamoorthi at VBC Risk Analytics

ICD-10 Data Lookup API: Improving Coding Speed and Accuracy

Chin Ramamoorthi at VBC Risk Analytics — Sun, 15 Mar 2026 12:34:35 +0000

If you have ever built or maintained a healthcare application that handles diagnosis codes, you know the pain of working with ICD-10. The code set contains over 70,000 entries, updates annually, and carries strict specificity requirements that can make or break a claim. Manual lookups are slow, error-prone, and do not scale.

The ICD-10 Data Lookup API from VBC Risk Analytics addresses these challenges by providing RESTful access to the full ICD-10-CM and ICD-10-PCS code sets. Rather than maintaining a local database that you need to update every October, you get a set of healthcare apis that covers code search, tabular data, external causes, neoplasm tables, drug indices, and procedure codes — all kept current by the provider. For developers building EHR integrations, claims processing systems, or coding assistance tools, this kind of medical coding lookup service can significantly reduce development time and improve data quality downstream.

Quick Start

The API follows standard REST conventions. Base URL, API key in the header, JSON responses:

import requests

BASE_URL = "https://restapi.npidataservices.com/icd10/api/v1"
HEADERS = {"ApiKey": "YOUR_API_KEY"}

**Search for a condition**
response = requests.get(
    f"{BASE_URL}/getICD10Code",
    params={"query": "type 2 diabetes with chronic kidney disease"},
    headers=HEADERS
)

results = response.json()

That is all the boilerplate you need. Every endpoint works the same way — GET request, query parameters, API key header, JSON back.

The Seven Endpoints

The API exposes seven endpoints. Together they cover the entire ICD-10 reference — the same content that coders traditionally navigate through print manuals, encoder software, or the CMS website, but accessible programmatically.

/getICD10Code — Iterative Code Search

This is the endpoint most developers will use first. Given a clinical term like "chronic obstructive pulmonary disease" or "hip fracture," it returns matching codes and index entries. The search is iterative — you can start broad, examine results, and refine by passing an index parameter to drill into a specific branch.

Think of it as the programmatic equivalent of a coder typing a term into an encoder's search box.

**Broad search**
results = requests.get(f"{BASE_URL}/getICD10Code",
    params={"query": "pneumonia"}, headers=HEADERS).json()

# Narrow into a specific index branch
refined = requests.get(f"{BASE_URL}/getICD10Code",
    params={"query": "pneumonia", "index": "aspiration"},
    headers=HEADERS).json()

/getICD10Index — Alphabetic Index Browse

The ICD-10-CM Alphabetic Index is the traditional starting point for code lookup. This endpoint mirrors that experience — browse by letter, then by main term. Useful for building autocomplete interfaces where a user types a condition name and gets progressively filtered suggestions.


**All index entries under "D"**
requests.get(f"{BASE_URL}/getICD10Index",
    params={"letter": "D"}, headers=HEADERS)

**Narrow to "Diabetes" specifically**
requests.get(f"{BASE_URL}/getICD10Index",
    params={"letter": "D", "main_term": "Diabetes"}, headers=HEADERS)

/getICD10Details — Tabular Data

Once you have a code or code range from the index, this endpoint gives you the full tabular detail — descriptions, Includes notes, Excludes1 and Excludes2 rules, coding guidelines, and specificity requirements. You can query at three levels of granularity: entire chapter, section range, or specific diagnosis code.

**Full detail for a specific code**
requests.get(f"{BASE_URL}/getICD10Details",
    params={"diag_code": "E11.22"}, headers=HEADERS)

**Browse the entire diabetes section**
requests.get(f"{BASE_URL}/getICD10Details",
    params={"section_range": "E08-E13"}, headers=HEADERS)

**Pull an entire chapter**
requests.get(f"{BASE_URL}/getICD10Details",
    params={"chapter": "9"}, headers=HEADERS)

This is the endpoint you use for validation — confirming whether a code is a billable terminal code or a header that requires additional specificity.

/getICD10EIndex — External Causes Index

Injury and trauma applications need external cause codes (V00-Y99) to describe how an injury occurred. This endpoint provides the External Causes of Morbidity index — essential for emergency department systems and workers' compensation platforms.


**Look up fall-related external cause codes**
requests.get(f"{BASE_URL}/getICD10EIndex",
    params={"letter": "F", "main_term": "Fall"}, headers=HEADERS)

/getICD10Drug — Table of Drugs and Chemicals

Maps substances to their ICD-10 codes for poisoning, adverse effects, and underdosing. Valuable for pharmacy applications, poison control integrations, and any system that needs to code substance-related encounters.


**Browse drug entries starting with "A" (Aspirin, Acetaminophen, etc.)**
requests.get(f"{BASE_URL}/getICD10Drug",
    params={"letter": "A"}, headers=HEADERS)

/getICD10Neo — Neoplasm Table

Oncology coding requires mapping anatomical sites to neoplasm codes across six behavior categories (malignant primary, malignant secondary, in situ, benign, uncertain, unspecified). This endpoint provides that specialized lookup.


**Browse neoplasm entries (Breast, Brain, Bone, etc.)**
requests.get(f"{BASE_URL}/getICD10Neo",
    params={"letter": "B"}, headers=HEADERS)

/getICD10PCSTabular — Procedure Codes

For inpatient procedure coding, this endpoint provides ICD-10-PCS code details. PCS uses a fundamentally different structure from ICD-10-CM — seven-character codes built from tables rather than hierarchical categories — and this endpoint handles that complexity.


**Look up a PCS code section**
requests.get(f"{BASE_URL}/getICD10PCSTabular",
    params={"code": "0210"}, headers=HEADERS)

Putting It Together: A Practical Client

The most common integration pattern combines search and detail into a two-step workflow — find the code, then get the full context:

class ICD10Client:
    def __init__(self, api_key):
        self.base = "https://restapi.npidataservices.com/icd10/api/v1"
        self.session = requests.Session()
        self.session.headers.update({"ApiKey": api_key})

    def search(self, query, index=None):
        params = {"query": query}
        if index:
            params["index"] = index
        return self.session.get(
            f"{self.base}/getICD10Code", params=params, timeout=5
        ).json()

    def details(self, diag_code):
        return self.session.get(
            f"{self.base}/getICD10Details",
            params={"diag_code": diag_code}, timeout=5
        ).json()

    def index(self, letter, main_term=None):
        params = {"letter": letter}
        if main_term:
            params["main_term"] = main_term
        return self.session.get(
            f"{self.base}/getICD10Index", params=params, timeout=5
        ).json()

# Usage
client = ICD10Client("YOUR_API_KEY")
results = client.search("heart failure")
detail = client.details("I50.9")
browse = client.index("H", "Heart")

Note the use of requests.Session() — this reuses the underlying TCP connection, which makes a meaningful difference when you are making many sequential calls.

Caching Strategy

ICD-10 codes change once a year on October 1. This makes aggressive caching both safe and highly effective:

from functools import lru_cache

@lru_cache(maxsize=5000)
def get_code_detail(client, diag_code):
    return client.details(diag_code)

For production systems, use Redis with a TTL that expires around the next annual update:

import redis, json
from datetime import datetime

cache = redis.Redis()

def cached_details(client, code):
    key = f"icd10:{code}"
    hit = cache.get(key)
    if hit:
        return json.loads(hit)
    data = client.details(code)
    # TTL until next October 1
    now = datetime.now()
    next_oct = datetime(now.year if now.month < 10 else now.year + 1, 10, 1)
    cache.setex(key, int((next_oct - now).total_seconds()), json.dumps(data))
    return data

Concurrent Lookups

When you need to look up multiple codes at once — common in claims processing and batch validation — use async to parallelize:

import httpx, asyncio

async def batch_lookup(api_key, codes):
    async with httpx.AsyncClient() as client:
        tasks = [
            client.get(
                "https://restapi.npidataservices.com/icd10/api/v1/getICD10Details",
                params={"diag_code": c},
                headers={"ApiKey": api_key}, timeout=10
            ) for c in codes
        ]
        responses = await asyncio.gather(*tasks, return_exceptions=True)
        return {
            c: r.json() if not isinstance(r, Exception) else None
            for c, r in zip(codes, responses)
        }

codes = ["E11.22", "I50.9", "J44.1", "N18.3", "F32.1"]
results = asyncio.run(batch_lookup("YOUR_API_KEY", codes))

Error Handling

Healthcare APIs demand careful error handling because incorrect data can affect patient care and financial outcomes. Key considerations:

401 means missing or invalid ApiKey — do not retry, fix the credential
429 means rate limited — implement exponential backoff
Timeouts — set 5s for interactive workflows, 30s for batch, and retry on transient failures
Ambiguous results — when search returns multiple matches, surface all options to the user rather than auto-selecting. In healthcare coding, the difference between two similar codes can have significant clinical and financial implications

import time

def safe_call(client, code, retries=3):
    for attempt in range(retries):
        try:
            return client.details(code)
        except requests.exceptions.HTTPError as e:
            if e.response.status_code == 401:
                raise ValueError("Invalid ApiKey")
            if e.response.status_code == 429:
                time.sleep(2 ** attempt)
                continue
            raise
        except requests.exceptions.Timeout:
            if attempt < retries - 1:
                continue
            raise

Why Use an API Instead of a Local Database?

You could download the CMS ICD-10 files and build your own lookup. Many organizations do. But maintaining it means:

Parsing CMS release files every October and applying updates
Building and maintaining search, hierarchy navigation, and validation logic
Handling the separate structures for CM (diagnosis), PCS (procedures), drugs, neoplasms, and external causes
Testing every update cycle for regressions

An ICD-10 code lookup API from NPI Data Services externalizes all of that. You get a stable interface, current data, and seven focused endpoints that cover the full ICD-10 reference. The trade-off is API dependency and latency — which caching largely mitigates.

Getting Started

If you are building healthcare applications that need diagnosis or procedure code lookup, integrating the ICD-10 data lookup service early saves significant time. The integration is straightforward — standard REST, JSON responses, API key auth. Most developers can have a working prototype within a couple of hours.

Start with /getICD10Code for search and /getICD10Details for validation. Add the specialty endpoints (Drug, Neoplasm, External Causes, PCS) as your application requires.

Full Swagger documentation: ICD10 Data Lookup API

Building a Healthcare API Platform for Risk Adjustment: Architecture, Endpoints, and Lessons Learned

Chin Ramamoorthi at VBC Risk Analytics — Wed, 04 Mar 2026 02:38:45 +0000

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.

RAF Score API

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.

RAF Batch

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.

ICD10 Data Lookup

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.

Provider Verification API

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.

RADV Audit

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:

Healthcare APIs

Or reach out directly:

Web: www.vbcriskanalytics.com/contact
Email: contact@vbcriskanalytics.com

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.