autoicd 0.6.0

Official Python SDK for the AutoICD API — clinical text to ICD-10-CM and ICD-11 diagnosis codes, powered by AI and medical NLP. Includes ICD-10/ICD-11 crosswalk.

AutoICD API — Python SDK

Official Python SDK for the AutoICD API — clinical text to ICD-10-CM and ICD-11 diagnosis codes, powered by AI and medical NLP.

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

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

---

Why AutoICD API

AI-Powered ICD-10 & ICD-11 Coding	Clinical NLP extracts diagnoses from free-text notes and maps them to ICD-10-CM or ICD-11 codes — no manual lookup required
74,000+ ICD-10-CM Codes	Full 2025 code set enriched with SNOMED CT synonyms for comprehensive matching
ICD-11 Support	Search and look up ICD-11 codes, with full ICD-10 ↔ ICD-11 crosswalk mappings
Negation & Context Detection	Knows the difference between "patient has diabetes" and "patient denies diabetes" — flags negated, historical, uncertain, and family-history mentions
PHI De-identification	HIPAA-compliant anonymization of names, dates, SSNs, phone numbers, emails, addresses, MRNs, and ages
Confidence Scoring	Every code match includes a similarity score and confidence level so you can set your own acceptance thresholds
Spell Correction	Handles misspellings in clinical text — "diabeties" still maps to the right code
Fully Typed	Complete type annotations for all requests and responses

---

Install

pip install autoicd

uv / poetry / pdm

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

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"

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:

Condition	ICD-10 Code	Description
Hypertension	I10	Essential (primary) hypertension
Type 2 Diabetes	E11.9	Type 2 diabetes mellitus without complications
Depression	F32.9	Major depressive disorder, single episode, unspecified
Anxiety	F41.1	Generalized anxiety disorder
Low Back Pain	M54.5	Low back pain
COPD	J44.9	Chronic obstructive pulmonary disease, unspecified
Heart Failure	I50.9	Heart failure, unspecified
UTI	N39.0	Urinary tract infection, site not specified
Pneumonia	J18.9	Pneumonia, unspecified organism
Atrial Fibrillation	I48.91	Unspecified atrial fibrillation
Obesity	E66.01	Morbid (severe) obesity due to excess calories
GERD	K21.9	Gastro-esophageal reflux disease without esophagitis
Hypothyroidism	E03.9	Hypothyroidism, unspecified
CKD	N18.9	Chronic kidney disease, unspecified

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.

Method	Description
client.code(text, options?)	Code clinical text to ICD-10-CM diagnoses
client.anonymize(text)	De-identify PHI/PII in clinical text
client.icd10.search(query, options?)	Search ICD-10-CM codes by description
client.icd10.get(code)	Get details for an ICD-10-CM code (incl. ICD-11 crosswalk)
client.icd11.search(query, options?)	Search ICD-11 codes by description
client.icd11.get(code)	Get details for an ICD-11 code (incl. ICD-10 crosswalk)

---

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,
)

---

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
• MCP Server — For Claude Desktop, Cursor, VS Code
• SNOMED CT & UMLS Cross-References — Terminology mappings
• ICD-10-CM 2025 Code Set — Official CMS reference

---

License

MIT