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 (new free keys paused)
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	current FY	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 Pro+

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	current FY	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|V08": []
    }
  }
}

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	current FY	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	current FY	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	current FY	Fiscal year
limit	query	int	10	Max suggestions (1-50)

Abbreviation Expansion

POST /expand Free

Expand all medical abbreviations in a text string.

Length limit: 500 characters on the Free tier, 10,000 on Pro and Enterprise. Over the limit returns 413. This endpoint normalizes shorthand before an index lookup — it is not intended for whole clinical notes.

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 verified, billable ICD-10-CM codes. Every code returned is valid in the official ICD-10-CM code set for the requested fiscal year, and the verification report flags any coding-convention issue for the coder to resolve.

Request

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

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

Response

{
  "success": true,
  "data": {
    "success": true,
    "codes_mentioned": ["E11.22", "N18.30"],
    "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,
          "in_official_code_set": true
        }
      ],
      "confidence_score": 0.95,
      "codes_not_returned": [],
      "sequence_adjusted": false
    }
  }
}

Verification Fields

Field	Description
confidence_score	0.0-1.0 confidence score (>= 0.8 = high, < 0.5 = low)
verified_codes	Each returned code with its `in_official_code_set` and `is_billable` flags
findings	Array of issues found (excludes1 conflicts, missing companion codes)
codes_not_returned	Codes left out of the result because they did not meet the official ICD-10-CM code set or a coding convention
sequence_adjusted	Whether the codes are in the order ICD-10-CM sequencing conventions require (for example, code first)

Batch Operations

POST /batch/codes Pro+

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

Request

{
  "codes": ["E11.22", "N18.30", "Z99.999"],
  "year": 2025,
  "include_inherited": true
}

Response

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

POST /batch/hcc Pro+

Bulk HCC mapping lookup.

Request

{
  "codes": ["E11.22", "N18.30"],
  "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.30"],
  "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; up to 500 pages parsed)
year	int	current FY	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": "received" }

Workflow

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

Status values: received → processing → complete (or failed)

GET /chart-review/{job_id} Pro+

Get chart review job status and results.

Response (complete)

{
  "job_id": "550e8400-...",
  "status": "complete",
  "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": {
      "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 Disabled

Disabled: returns 403. Keys are created from an account (POST /api/v1/keys) on a paid tier.

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 the Pro plan. See /pricing for current pricing.

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 Signed-in session

Customer-directed deletion of the coding data held under your own API keys (not a HIPAA right to deletion). Removes their coding traces, cache entries and chart-review jobs (with their extracted chart text), and recommendations made from those charts (with their evidence and reviewer actions), and records a proof of destruction per key. Coding sessions and recommendations not made from a chart are not removed by this action and follow their own retention. Audit and disclosure logs are retained.

This is an account action on your account page, authenticated by your sign-in session, never by an API key. A key bound to an organization is included only if you are an owner or admin of that organization; other keys are skipped and counted. Answers: 401 not signed in, 412 mfa_required when an affected organization requires MFA you have not enrolled in, 422 without the confirmation body.

Request

{ "confirm": "DELETE" }

Response

{
  "success": true,
  "deleted": {
    "coding_traces": 42,
    "coding_cache": 15,
    "chart_review_jobs": 3,
    "clinical_documents": 3,
    "recommendations": 5,
    "recommendation_evidence": 9,
    "reviewer_actions": 2
  },
  "keys": 2,
  "skipped_keys": { "not_a_member": 0, "role_too_low": 0 },
  "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 Scrape token or API key

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 (submitted text, steps, codes)	Not stored by default. Only for an API key whose stored-coding setting we have turned on at your organization's request; then 365 days (auto-purged)	Immediate via DELETE /billing/data
Coding result cache	Not stored by default. Same per-key rule; then 90 days (auto-purged)	Immediate via DELETE /billing/data
Chart review jobs (encrypted result and extracted chart text; chart review requires an organization with an executed BAA; the job record is not governed by the stored-coding setting, but the per-condition coding traces a review produces follow the same per-key rule as any other coding run)	90 days after the job completes or fails, then auto-purged with everything derived from it	Immediate via DELETE /billing/data
Uploaded chart (stored encrypted with its job)	Until the job finishes (completes or fails), then deleted. While the job runs, temporary working copies exist on disk (one encrypted, one decrypted for parsing); each is securely overwritten and unlinked when the job ends, and any left behind are swept after 60 minutes	Deleted with the job; disk copies securely overwritten + unlinked
Review recommendations (include the condition text, encrypted)	Only when your organization turns review mode on; chart-less ones 365 days, chart ones with their job	Organization data deletion
Coding sessions you create (each turn's text, encrypted)	For the session, then 30 days after it closes or expires	Organization data deletion
Audit logs	Permanent	Not deletable (compliance)

The public demo (/try) stores no coding content. Neither, today, do MCP or the OpenAI- and Anthropic-tool endpoints, whatever the key's setting. For key-authenticated calls we record usage metering (endpoint, status and timing, no content) for billing; anonymous demo calls record none.

Technical Specifications

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	Current fiscal year (advances each Oct 1; FY2027 since 2026-10-01)
Max batch size	50 codes
Max document size	20 MB; up to 500 pages parsed
Encryption at rest	AES-256-GCM
AI processing of PHI	Clinical text you send is processed by our AI model provider (OpenAI, called directly) under a signed HIPAA Business Associate Agreement, in line with HIPAA, with zero data retention and no use of your data to train models. The safeguard is the executed BAA, not removing identifiers. Scanned pages are read by Azure AI Document Intelligence under Microsoft's BAA; Microsoft stores the submitted document and its analysis result for 24 hours after the analysis completes and then deletes them, so zero retention does not apply to OCR. PHI requires an organization with an executed BAA.
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 (complete)

Account Management

Request

Response

Request

Request

Response

Request

Response

Health & Monitoring

Integration Endpoints

Data Retention

Technical Specifications

Ready to Build?