API Documentation - ICD-10 Coding API

Authentication

All endpoints (except signup) require an API key via either header:

Authorization: Bearer icd10_xxxx...

# or

X-API-Key: icd10_xxxx...

Keys are issued at signup and shown once. They cannot be retrieved again. See API pricing →

Rate Limits

Tier	Requests/Day	Requests/Min	Features
Free	100	10	Lookup, search, expand, HCC
Pro	10,000	100	All Free + AI coding, batch, chart review
Enterprise	Unlimited	500	All Pro + custom SLA

Rate limit headers are included on every response: X-RateLimit-Limit-Minute, X-RateLimit-Remaining-Minute, X-RateLimit-Reset-Minute, X-RateLimit-Limit-Day, X-RateLimit-Remaining-Day.

Error Codes

Status	Meaning	When
400	Bad Request	Invalid parameters, file too large, batch > 50 codes
401	Unauthorized	Missing or invalid API key
403	Forbidden	Feature not available for your tier
404	Not Found	Code or resource not found
409	Conflict	Account already exists (signup)
422	Unprocessable Entity	Validation failed on request body
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Unexpected server error
503	Service Unavailable	External service down

Error response format

{
  "detail": "AI coding is not enabled for your API key tier"
}

Code Lookup

GET /codes/{code} Free

Look up an ICD-10-CM code with full tabular details and inherited instructional notes.

Parameters

Name	In	Type	Default	Description
code	path	string	required	ICD-10-CM code (e.g., E11.22)
year	query	int	2025	Fiscal year version
include_inherited	query	bool	true	Include notes from parent categories
include_hcc	query	bool	false	Include HCC mappings inline
include_weights	query	bool	false	Include RAF weights (requires include_hcc)
payment_year	query	int	null	Payment year for weight lookup

Response

{
  "success": true,
  "data": {
    "code": "E11.22",
    "description": "Type 2 diabetes mellitus with diabetic chronic kidney disease",
    "short_description": "Type 2 diabetes with CKD",
    "is_billable": true,
    "chapter": { "number": "4", "name": "Endocrine, nutritional and metabolic diseases" },
    "section": { "id": "E08-E13", "description": "Diabetes mellitus" },
    "includes": [],
    "excludes1": ["Type 1 diabetes mellitus (E10.-)"],
    "use_additional_code": ["Use additional code to identify stage of CKD (N18.1-N18.6)"],
    "inherited_notes": [
      { "type": "excludes1", "text": "Type 1 diabetes mellitus (E10.-)", "from_code": "E11" }
    ]
  }
}

GET /codes/{code}/hcc Free

Get HCC risk adjustment mappings for a code.

Parameters

Name	In	Type	Default	Description
code	path	string	required	ICD-10-CM code
year	query	int	2025	Fiscal year version
detail	query	bool	false	Include symbol breakdown and payment flags
include_weights	query	bool	false	Include RAF weights
payment_year	query	int	null	Payment year for weights

Response

{
  "success": true,
  "data": {
    "code": "E11.22",
    "has_hcc": true,
    "categories": {
      "CMS-HCC|V28": ["HCC37"],
      "CMS-HCC|V24": ["HCC18"],
      "RxHCC|V06": []
    }
  }
}

GET /codes/{code}/children Free

List all child codes under a parent category.

Parameters

Name	In	Type	Default	Description
code	path	string	required	Parent code (e.g., E11)
year	query	int	2025	Fiscal year version

Response

{
  "success": true,
  "data": [
    { "code": "E11.0", "description": "Type 2 DM with hyperosmolarity", "is_billable": false },
    { "code": "E11.00", "description": "...without NKHHC", "is_billable": true }
  ]
}

Search

GET /search Free

Search the ICD-10-CM alphabetic index or tabular descriptions.

Parameters

Name	In	Type	Default	Description
q	query	string	required	Search query (1-500 chars)
year	query	int	2025	Fiscal year (2014-2030)
main_term	query	string	null	Main index term for hierarchical search
subterms	query	list[string]	null	Subterms for refinement (max 10)
mode	query	string	"index"	"index" (alphabetic) or "tabular" (descriptions)
limit	query	int	20	Max results (1-100)

Response (index mode)

{
  "success": true,
  "data": {
    "mode": "index",
    "query": "diabetes",
    "matches": [
      { "term": "Diabetes, diabetic", "code": "E11.9", "level": 0, "see": null, "see_also": null }
    ],
    "total": 5
  }
}

GET /search/suggest Free

Typeahead autocomplete suggestions.

Parameters

Name	In	Type	Default	Description
q	query	string	required	Partial query (1-500 chars)
year	query	int	2025	Fiscal year
limit	query	int	10	Max suggestions (1-50)

Abbreviation Expansion

POST /expand Free

Expand all medical abbreviations in a text string.

Request

{ "text": "DM2 w/ CKD stage 3" }

Response

{
  "success": true,
  "data": {
    "original_text": "DM2 w/ CKD stage 3",
    "expanded_text": "diabetes mellitus type 2 with chronic kidney disease stage 3",
    "expansions": [
      {
        "original": "DM2",
        "expanded": "diabetes mellitus type 2",
        "main_term_hint": "Diabetes",
        "subterm_hints": ["type 2"]
      }
    ],
    "expansion_count": 2
  }
}

POST /expand/term Free

Expand a single abbreviation.

Request

{ "term": "DM2" }

AI Coding

POST /code Pro+

Convert a natural-language clinical condition to ICD-10-CM codes. The AI follows the standard 5-step coding workflow (normalize, index lookup, tabular verify, specificity check, combination code check) and every result is run through a deterministic verification engine.

Request

{
  "condition": "DM2 with CKD stage 3",
  "year": 2025,
  "include_hcc": false
}

Field	Type	Default	Description
condition	string	required	Natural language condition
year	int	2025	ICD-10-CM fiscal year
include_hcc	bool	false	Include HCC info

Response

{
  "success": true,
  "data": {
    "success": true,
    "codes_mentioned": ["E11.22", "N18.3"],
    "reasoning": "Type 2 diabetes with CKD maps to E11.22...",
    "confidence": "high",
    "verification": {
      "verified_codes": [
        {
          "code": "E11.22",
          "description": "Type 2 diabetes mellitus with diabetic chronic kidney disease",
          "is_billable": true,
          "tool_verified": true,
          "db_verified": true
        }
      ],
      "confidence_score": 0.95,
      "codes_removed": [],
      "codes_reordered": false
    }
  }
}

Verification Fields

Field	Description
confidence_score	0.0-1.0 deterministic score (>= 0.8 = high, < 0.5 = low)
verified_codes	Each code with db_verified, is_billable, tool_verified flags
findings	Array of issues found (excludes1 conflicts, missing companion codes)
codes_removed	Codes that failed existence verification (removed from result)
codes_reordered	Whether code-first sequencing rules required reordering

Batch Operations

POST /batch/codes Pro+

Bulk code lookup (up to 50 codes per request).

Request

{
  "codes": ["E11.22", "N18.3", "I10"],
  "year": 2025,
  "include_inherited": true
}

Response

{
  "success": true,
  "data": {
    "results": {
      "E11.22": { "code": "E11.22", "description": "...", "is_billable": true },
      "N18.3": { "code": "N18.3", "description": "...", "is_billable": true }
    },
    "not_found": ["I10"],
    "found_count": 2,
    "not_found_count": 1
  }
}

POST /batch/hcc Pro+

Bulk HCC mapping lookup.

Request

{
  "codes": ["E11.22", "N18.3"],
  "year": 2025,
  "include_weights": true,
  "payment_year": 2025
}

POST /batch/hcc/suppress Pro+

Bulk HCC lookup with hierarchy suppression and RAF score calculation.

Request

{
  "codes": ["E11.22", "N18.3"],
  "year": 2025,
  "model_type": "CMS-HCC",
  "model_version": "V28",
  "payment_year": 2025,
  "segment": "community_nondual_aged"
}

Field	Type	Default	Description
codes	list[string]	required	Up to 50 ICD-10-CM codes
model_type	string	"CMS-HCC"	CMS-HCC, RxHCC, HHS-HCC, ESRD
model_version	string	"V28"	Model version
segment	string	"community_nondual_aged"	Beneficiary segment

Response

{
  "success": true,
  "data": {
    "model_type": "CMS-HCC",
    "model_version": "V28",
    "active_categories": [...],
    "suppressed_categories": [...],
    "total_raf_score": 0.500
  }
}

Chart Review

POST /chart-review/upload Pro+

Upload a medical document for AI-powered chart review. Processing is asynchronous.

Content-Type: multipart/form-data

Concurrent limit: 3 active jobs per API key

Supported formats: PDF, DOCX, TXT, RTF, CSV, XLSX, XLS, XML (C-CDA), JSON (FHIR), HL7v2, PNG, JPG, TIFF, BMP, HEIC, WEBP

Field	Type	Default	Description
file	file	required	Medical chart (max 20 MB, 50 pages)
year	int	2025	ICD-10-CM fiscal year
include_hcc	bool	false	Include HCC info on coded conditions
use_batch	bool	false	Use batch operations for coding

Response (202)

{ "job_id": "550e8400-e29b-41d4-a716-446655440000", "status": "pending" }

Workflow

Submit document via POST /chart-review/upload
Receive job_id immediately
Poll GET /chart-review/{job_id} until status is "completed" or "failed"

Stages: pending → parsing → extracting → coding → completed

GET /chart-review/{job_id} Pro+

Get chart review job status and results.

Response (completed)

{
  "job_id": "550e8400-...",
  "status": "completed",
  "filename": "patient_chart.pdf",
  "conditions_found": 5,
  "conditions_coded": 5,
  "result": {
    "document": { "filename": "patient_chart.pdf", "page_count": 3 },
    "demographics": { "member_name": "...", "date_of_service": "..." },
    "current_conditions": [
      {
        "condition_text": "Type 2 diabetes with CKD stage 3",
        "supporting_evidence": "Assessment section, page 2",
        "icd10_codes": [
          { "code": "E11.22", "description": "...", "is_billable": true, "confidence": "high" }
        ]
      }
    ],
    "stats": {
      "total_tokens": 6700,
      "conditions_found": 5,
      "conditions_coded": 5
    }
  }
}

GET /chart-review/jobs Pro+

List chart review jobs for the authenticated API key.

Name	In	Type	Default	Description
limit	query	int	20	Max jobs to return
offset	query	int	0	Pagination offset

Account Management

POST /billing/signup No auth

Create a free account and API key. No authentication required.

Rate limit: 5 signups per IP per hour

Request

{ "email": "[email protected]" }

Response

{
  "success": true,
  "data": {
    "email": "[email protected]",
    "api_key": "icd10_a1b2c3d4...",
    "tier": "free",
    "message": "Save your API key — it cannot be retrieved again."
  }
}

POST /billing/checkout Authenticated

Create a Stripe Checkout session to upgrade to Pro ($99/mo).

Request

{
  "success_url": "https://yoursite.com/billing?status=success",
  "cancel_url": "https://yoursite.com/billing?status=cancel"
}

GET /billing/subscription Authenticated

Get current subscription status.

{
  "success": true,
  "data": {
    "tier": "pro",
    "subscription_status": "active",
    "current_period_end": "2025-05-01T00:00:00Z"
  }
}

POST /billing/portal Authenticated

Get a Stripe Customer Portal URL for managing subscription and payment methods.

POST /billing/keys/rotate Authenticated

Rotate your API key. Old key remains valid during the grace period.

Request

{ "grace_period_minutes": 60 }

Response

{
  "success": true,
  "data": {
    "new_api_key": "icd10_x9y8z7...",
    "new_key_prefix": "icd10_x9y8",
    "grace_period_minutes": 60,
    "message": "Save your new API key — it cannot be retrieved again."
  }
}

DELETE /billing/data Authenticated

Delete all your PHI data (HIPAA right to deletion). Removes coding traces, cache entries, and chart review jobs. Audit logs are retained for compliance.

Response

{
  "success": true,
  "deleted": {
    "coding_traces": 42,
    "coding_cache": 15,
    "chart_review_jobs": 3
  },
  "note": "Audit logs are retained for compliance."
}

Health & Monitoring

GET /health No auth

Liveness check. Always returns 200 if the process is running.

{ "status": "healthy", "service": "icd10-api" }

GET /health/ready No auth

Readiness check. Returns 503 if the database is unreachable.

GET /metrics No auth

Prometheus-compatible metrics endpoint. Includes HTTP request latency histograms, error counts, and database connection pool gauges.

Integration Endpoints

Path	Description
/mcp	MCP server for Claude, Cursor, Windsurf
/tools/openai	OpenAI function calling schemas
/tools/anthropic	Anthropic tool_use schemas

Data Retention

Data	Retention	Deletion
Coding traces	365 days (auto-purged)	Immediate via DELETE /billing/data
Coding cache	90 days (auto-purged)	Immediate via DELETE /billing/data
Chart review jobs	90 days (auto-purged)	Immediate via DELETE /billing/data
Upload files	60 minutes (auto-deleted)	Secure overwrite + unlink
Audit logs	Permanent	Not deletable (compliance)

Base URL	https://api.accurecord.io/api/v1
Protocol	HTTPS (TLS 1.2+)
Auth	Authorization: Bearer or X-API-Key
Key format	icd10_ + 64 hex characters
Response format	JSON
Default ICD-10 year	FY2025
Max batch size	50 codes
Max document size	20 MB, 50 pages
Encryption at rest	AES-256-GCM
PHI scrubbing	SSN, MRN, DOB, phone, email, address removed before LLM
Concurrent chart jobs	3 per API key

ICD-10 Coding API Docs

Authentication

Rate Limits

Error Codes

Code Lookup

Parameters

Response

Parameters

Response

Parameters

Response

Search

Parameters

Response (index mode)

Parameters

Abbreviation Expansion

Request

Response

Request

AI Coding

Request

Response

Verification Fields

Batch Operations

Request

Response

Request

Request

Response

Chart Review

Response (202)

Response (completed)

Account Management

Request

Response

Request

Request

Response

Response

Health & Monitoring

Integration Endpoints

Data Retention

Technical Specifications

Ready to Build?