AutoICD API - Python SDK

Official Python SDK for the AutoICD API - AI medical coding that converts clinical text to ICD-10-CM, ICD-11, and ICF codes using medical NLP. Automate ICD-10 coding, ICF functioning classification, and disability assessment in your application.

Single dependency (httpx). Works in Python 3.10+.

Built for EHR integrations, health-tech platforms, medical billing, clinical decision support, and revenue cycle management.

What's new - 2026-05-05

• Phase 3 unified reference lookup. A single client.reference.lookup(system, code) covers ICD-10-CM, ICD-11, ICF, LOINC, SNOMED CT, UMLS, and RxNorm. The legacy per-system getters (icd10.get, icd11.get, icf.lookup, loinc.lookup) keep working but the underlying routes now emit Deprecation and Sunset headers.
• Phase 4 SNOMED CT, UMLS, and RxNorm coverage. Lookup canonical concept records (preferred terms, synonyms, semantic types) and search those vocabularies via client.reference.search(system, query).
• Cross-references everywhere. ICD-10, ICD-11, LOINC, SNOMED, UMLS, and RxNorm records all carry cross_references keyed by target system, so you can pivot between vocabularies without extra calls.

Why AutoICD API

Install

pip install autoicd

uv add autoicd
poetry add autoicd
pdm add autoicd

Quick Start

from autoicd import AutoICD

client = AutoICD(api_key="sk_...")

result = client.code(
    "Patient has type 2 diabetes and essential hypertension"
)

for entity in result.entities:
    print(entity.entity_text, "→", entity.codes[0].code)
# "type 2 diabetes"       → "E11.9"
# "essential hypertension" → "I10"

Features

Chart Audit (HCC gap capture, RADV defense, specificity, denial risk)

Audit a chart to surface coding gaps, unsupported codes, specificity upgrades, and denial-risk flags in one call. Every finding carries extractive evidence spans. HCC gaps include RAF-weighted revenue estimates using the CMS PY2026 V22 and V28 community models.

from autoicd import AutoICD, AuditRequest, AuditCode, AuditContext, AuditPatientContext

client = AutoICD(api_key="sk_...")

audit = client.audit(AuditRequest(
    text=(
        "68yo M, type 2 diabetes stable on metformin, chronic systolic heart failure "
        "on furosemide, edema controlled. A1c 7.4 today."
    ),
    codes=[AuditCode(code="E11.9", kind="icd10")],
    capabilities=["hcc", "radv", "specificity", "denial", "problem_list"],
    context=AuditContext(
        patient=AuditPatientContext(coverage="medicare_advantage"),
        hcc_model="both",
    ),
))

print(f"Missed revenue: ${audit.totals.estimated_revenue_recovery:.0f}")
print(f"RADV exposure:  ${audit.totals.radv_exposure:.0f}")

for m in audit.missed:
    cat = m.hcc_category or "non-HCC"
    model = m.hcc_model or ""
    print(f"MISSED {m.code} ({cat} {model}) -> ${m.estimated_revenue or 0:.0f}: {m.description}")
    for span in m.evidence:
        print(f'    evidence: "{span.quote}" [{span.start}-{span.end}]')

Default behavior runs all five capabilities. Pass capabilities=["hcc"] to run a targeted audit. The Audit endpoint also accepts plain dicts if you prefer not to import the dataclasses.

hcc_model: use "v22", "v28", or "both" (default). CMS PY2026 MA payment uses V22 and V28 as the two main community models. V24 is the ESRD-specific model and is not accepted here.

Read more about the Audit endpoint at autoicdapi.com/audit.

Unified Reference Lookup (ICD-10, ICD-11, ICF, LOINC, SNOMED, UMLS, RxNorm)

One call to fetch canonical record data for any code in any supported system. The response is a tagged dataclass - switch on result.system to access the system-specific shape.

icd10 = client.reference.lookup("icd-10-cm", "E11.9")
print(icd10.record.long_description)
print(icd10.record.cross_references)  # {"snomed": [...], "umls": [...], "rxnorm": [...]}

concept = client.reference.lookup("snomed-ct", "44054006")
print(concept.record.preferred_term)  # "Diabetes mellitus type 2"
print(concept.record.semantic_tag)    # "disorder"

cui = client.reference.lookup("umls", "C0011860")
print(cui.record.preferred_name)
print(cui.record.cross_references["snomed"])

drug = client.reference.lookup("rxnorm", "860975")  # metformin 500 MG
print(drug.record.name, drug.record.tty)

Supported system values: "icd-10-cm", "icd-11", "icf", "loinc", "snomed-ct", "umls", "rxnorm".

Reference Search (SNOMED CT, UMLS, RxNorm)

Free-text search the Neon-backed reference vocabularies. ICD-10, ICD-11, ICF, and LOINC keep their per-system search endpoints.

hits = client.reference.search("snomed-ct", "type 2 diabetes", limit=5)
for hit in hits.results:
    print(hit.code, hit.label, hit.meta)
    # 44054006 "Diabetes mellitus type 2 (disorder)" "disorder"

cuis = client.reference.search("umls", "metformin")
drugs = client.reference.search("rxnorm", "lisinopril 10 mg", limit=10)

Cross-Standard Code Translation

Translate a code between healthcare coding systems in one call. Forward from ICD-10 to ICD-11, SNOMED CT, UMLS, and ICF, plus reverse ICD-11 → ICD-10 and ICF → ICD-10. Built on CMS-published crosswalks, code-level SNOMED / UMLS concept IDs, and WHO ICF Core Sets.

from autoicd import AutoICD, TranslateRequest, TranslateFrom

client = AutoICD(api_key="sk_...")

result = client.translate(TranslateRequest(
    from_=TranslateFrom(code="E11.9", system="icd10"),
))

print(result.mappings["icd11"])
# [TranslateMapping(code="5A11", description="Type 2 diabetes mellitus", mapping_type="equivalent", ...)]
print(result.mappings["snomed"])
# [TranslateMapping(code="44054006", ...), TranslateMapping(code="73211009", ...)]
print(result.mappings["icf"])
# [TranslateMapping(code="b540", description="General metabolic functions", component="b", ...)]

Narrow the targets when you only need specific systems:

result = client.translate(TranslateRequest(
    from_=TranslateFrom(code="I50.9", system="icd10"),
    to=["icd11"],
))

Requested systems that aren't reachable from the source are returned in unsupported_targets rather than raising, so clients can request a broad target list and use whatever comes back. Plain dicts are accepted too: client.translate({"from": {"code": "E11.9", "system": "icd10"}}).

Read more about the Translate endpoint at autoicdapi.com/interop.

Automated ICD-10 Medical Coding

Extract diagnosis entities from clinical notes and map them to ICD-10-CM codes. Each entity includes ranked candidates with confidence scores, negation status, and context flags.

result = client.code(
    "History of severe COPD with acute exacerbation. Patient denies chest pain."
)

for entity in result.entities:
    print(entity.entity_text)
    print(f"  Negated: {entity.negated}")
    print(f"  Historical: {entity.historical}")
    for match in entity.codes:
        print(
            f"  {match.code} - {match.description} "
            f"({match.confidence}, {match.similarity * 100:.1f}%)"
        )

Fine-tune results with coding options:

from autoicd import CodeOptions

result = client.code(
    "Patient presents with acute bronchitis and chest pain",
    options=CodeOptions(
        top_k=3,               # Top 3 ICD-10 candidates per entity (default: 5)
        include_negated=False, # Exclude negated conditions from results
    ),
)

ICD-10 Code Search

Search the full ICD-10-CM 2025 code set by description. Perfect for building code lookup UIs, autocomplete fields, and validation workflows.

results = client.icd10.search("diabetes mellitus")
# results.codes → [CodeDetail(code="E11.9", short_description="...", ...), ...]

from autoicd import SearchOptions
results = client.icd10.search("heart failure", options=SearchOptions(limit=5))

ICD-10 Code Details

Get full details for any ICD-10-CM code - descriptions, billable status, synonyms, hierarchy, and chapter classification.

detail = client.icd10.get("E11.9")
print(detail.code)              # "E11.9"
print(detail.long_description)  # "Type 2 diabetes mellitus without complications"
print(detail.is_billable)       # True
print(detail.synonyms["snomed"])  # ["Diabetes mellitus type 2", ...]
print(detail.chapter.title)       # "Endocrine, Nutritional and Metabolic Diseases"

ICD-11 Code Search

Search the ICD-11 code set by description. The AutoICD API includes the full WHO ICD-11 MMS hierarchy.

results = client.icd11.search("diabetes mellitus")
# results.codes → [ICD11CodeSearchResult(code="5A11", short_description="...", ...), ...]

results = client.icd11.search("heart failure", options=SearchOptions(limit=5))

ICD-11 Code Details & Crosswalk

Get full details for any ICD-11 code - descriptions, Foundation URI, hierarchy, synonyms, and ICD-10 crosswalk mappings.

detail = client.icd11.get("5A11")
print(detail.code)              # "5A11"
print(detail.short_description) # "Type 2 diabetes mellitus"
print(detail.foundation_uri)    # "http://id.who.int/icd/entity/1691003785"
print(detail.chapter.title)     # "Endocrine, nutritional or metabolic diseases"

# ICD-10 crosswalk
for mapping in detail.icd10_mappings:
    print(f"{mapping.code} - {mapping.description} ({mapping.mapping_type})")
    # "E11.9 - Type 2 diabetes mellitus without complications (equivalent)"

ICD-10 → ICD-11 Crosswalk

ICD-10 code details now include ICD-11 crosswalk mappings when available:

detail = client.icd10.get("E11.9")
for mapping in detail.icd11_mappings:
    print(f"{mapping.code} - {mapping.description}")
    # "5A11 - Type 2 diabetes mellitus"

ICF Functioning Codes

Look up WHO ICF categories, search the catalog, and access ICF Core Sets for 12+ conditions. To extract ICF functioning categories from clinical text, pass CodeOptions(include_icf=True) to client.code(); the response carries icf_entities alongside the ICD-10 results.

from autoicd import CodeOptions

# Extract ICF functioning categories during ICD-10 coding
result = client.code(
    "Patient with stroke and hemiplegia",
    CodeOptions(include_icf=True),
)
for entity in result.icf_entities or []:
    print(entity.entity_text, entity.codes[0].code)
    # "hemiplegia" "b730"

# Look up an ICF code
code = client.icf.lookup("d450")
print(code.title)  # "Walking"

# Search ICF codes
results = client.icf.search("mobility")

# Get ICF Core Set for a diagnosis
core_set = client.icf.core_set("E11.9")
print(core_set.condition_name)  # "Diabetes Mellitus"

PHI De-identification

Strip protected health information from clinical notes before storage or analysis. HIPAA-compliant de-identification for names, dates, SSNs, phone numbers, emails, addresses, MRNs, and ages.

result = client.anonymize(
    "John Smith, DOB 01/15/1980, MRN 123456, has COPD"
)

print(result.anonymized_text)
# "[NAME], DOB [DATE], MRN [MRN], has COPD"

print(result.pii_count)     # 3
print(result.pii_entities)  # [PIIEntity(text="John Smith", label="NAME", ...), ...]

Common ICD-10 Codes

The SDK can code any of the 74,000+ ICD-10-CM codes. Here are some of the most commonly coded conditions:

Browse all 74,000+ codes in the ICD-10-CM Code Directory or find codes by condition.

Use Cases

• EHR / EMR Integration - Auto-code clinical notes as providers type, reducing manual coding burden
• Medical Billing & RCM - Accelerate claim submission with accurate ICD-10 codes
• Clinical Decision Support - Map patient conditions to standardized codes for analytics and alerts
• Health-Tech SaaS - Add ICD-10 coding to your platform without building ML infrastructure
• Clinical Research - Extract and standardize diagnoses from unstructured medical records
• Insurance & Payer Systems - Validate and suggest diagnosis codes during claims processing
• Telehealth Platforms - Generate diagnosis codes from visit notes and transcriptions

Error Handling

from autoicd import (
    AutoICD,
    AuthenticationError,
    RateLimitError,
    NotFoundError,
)

try:
    result = client.code("...")
except AuthenticationError:
    # Invalid or revoked API key (401)
    ...
except RateLimitError as e:
    # Request limit exceeded (429)
    print(e.rate_limit.remaining, e.rate_limit.reset_at)
except NotFoundError:
    # ICD-10 code not found (404)
    ...

Rate limit info is available after every request:

client.code("...")
print(client.last_rate_limit)
# RateLimit(limit=1000, remaining=987, reset_at=datetime(...))

Configuration

client = AutoICD(
    api_key="sk_...",                   # Required - get yours at https://autoicdapi.com
    base_url="https://...",             # Default: https://autoicdapi.com
    timeout=60.0,                       # Default: 30.0 seconds
    http_client=httpx.Client(...),      # Custom httpx client (for proxies, mTLS, etc.)
)

Use as a context manager for automatic cleanup:

with AutoICD(api_key="sk_...") as client:
    result = client.code("Patient has diabetes")

API Reference

Full REST API documentation at autoicdapi.com/docs.

Types

All request and response types are exported:

from autoicd import (
    CodingResponse,
    CodingEntity,
    CodeMatch,
    CodeOptions,
    CodeDetail,
    CodeSearchResponse,
    AnonymizeResponse,
    PIIEntity,
    RateLimit,
    SearchOptions,
    ICD11CodeDetail,
    ICD11CodeDetailFull,
    ICD11CodeSearchResponse,
    CrosswalkMapping,
    ICFCodeDetail,
    ICFCodeSearchResponse,
    ICFCoreSetResponse,
)

Requirements

• Python 3.10+
• An API key from autoicdapi.com

Links

• AutoICD API - Homepage and API key management
• API Documentation - Full REST API reference
• ICD-10-CM Code Directory - Browse all 74,000+ diagnosis codes
• ICD-11 Code Directory - Browse the WHO ICD-11 MMS hierarchy
• ICD-10 ↔ ICD-11 Crosswalk - Map codes between revisions
• ICD-10 Codes by Condition - Find codes for common conditions
• TypeScript SDK - npm install autoicd
• AutoICD MCP Server - For Claude Desktop, Cursor, VS Code, Windsurf, and the remote endpoint at autoicdapi.com/api/mcp
• Postman Collection - Importable collection for the full REST surface
• SNOMED CT & UMLS Cross-References - Terminology mappings
• ICD-10-CM 2025 Code Set - Official CMS reference

License

MIT