Short answer. Parse the note, extract diagnoses and procedures with a quote for every fact, map them to the current ICD-10-CM, CPT and HCPCS files, attach a calibrated confidence score, and route every code to a certified coder. Evaluate on 100 notes stratified by specialty, then feed denials back into the prompt and retrieval layer. This is not a medical device or billing advice; human review and counsel review are required.
Scope and limits
Medical coding is not transcription. The note may document a diagnosis in narrative form, imply a procedure through a statement of time or technique, or omit a detail the coder would query. A model can extract candidate facts and map them to codes, but it cannot resolve an incomplete record, verify medical necessity or guarantee payment.
The API should return suggestions with evidence, not final codes. It can rank candidates, explain a code, flag documentation gaps and propose a clinician query. It must not auto-submit claims.
Note-to-code pipeline
The pipeline has six stages. Each stage should be observable and reversible, because a wrong code can start with a bad parse rather than a bad model.
- Ingest: receive the note through an authenticated endpoint, confirm the BAA and minimum-necessary data, and store the raw file in an access-controlled bucket.
- Parse: convert scanned or PDF notes to text with section boundaries; keep the page and character offsets.
- Extract: identify diagnoses, procedures, laterality, timing, acuity and modifiers, each with a supporting quote.
- Map: retrieve the current code descriptors and map facts to candidate codes; do not rely on model memory for code definitions.
- Validate: check code validity, specificity, bundling edits and evidence support; assign a calibrated confidence.
- Review: send every candidate to a certified coder, record accept/edit/reject and the reason, then release the claim.
Code systems
Use the authoritative files, not a scraped list or the model's memory. Each system has a different maintainer, update cadence and licensing rule.
| System | Maintainer | Used for | Update cadence |
|---|---|---|---|
| ICD-10-CM | CMS and CDC | Diagnoses, signs, symptoms and reasons for encounter | Annual, effective 1 October in the US |
| CPT | American Medical Association | Procedures, services and E/M levels | Annual, effective 1 January |
| HCPCS Level II | CMS | Supplies, drugs, durable equipment and services not in CPT | Quarterly updates |
| Modifiers | CMS and AMA | Laterality, multiple procedures, professional/technical components | With the parent code set |
| NCCI edits | CMS | Bundling and unbundling rules for claim scrubbing | Quarterly |
CPT requires a licence from the AMA for many commercial uses. Confirm your licence before embedding descriptors in a product. ICD-10-CM and HCPCS files are public, but the mapping logic and your internal playbook are not.
Evidence spans and confidence
Every suggested code needs a quote a coder can verify. It should identify the section, page and character range, and be copied from the note, not paraphrased. If the note says "patient denies chest pain", extracting "chest pain" as a diagnosis inverts the meaning; the evidence span exposes it.
{
"note_id": "note_01J...",
"coding_system": "ICD-10-CM",
"suggestions": [
{
"code": "E11.9",
"description": "Type 2 diabetes mellitus without complications",
"confidence": 0.91,
"evidence": {
"section": "Assessment",
"page": 2,
"start_char": 1840,
"end_char": 1912,
"quote": "Type 2 diabetes mellitus, currently without complications."
},
"documentation_gap": null,
"review_required": true
}
],
"queries": [
{"question": "Was the procedure performed on the left or right side?", "reason": "Laterality not documented."}
]
}
Confidence must be calibrated, not just copied from a model logprob. Bin predictions by confidence and measure accuracy in each bin on your gold set. If 90%-confidence codes are correct only 70% of the time, the number is misleading and the threshold for auto-suggestion should move.
Human review and audit trail
A certified coder should review every code before submission. The review screen should show the note, the evidence quote, the candidate code, the code description and any documentation query. The coder accepts, edits or rejects, and the reason is recorded.
The audit trail should capture the note version, parser version, model ID, prompt version, code-set release, candidate list, confidence, reviewer ID, decision, timestamp and the final claim. That record is what lets you investigate a denial or an audit months later. It also makes it possible to compare model versions without losing the human decision.
The 100-note eval and denial feedback
Build a gold set of 100 notes stratified by specialty, note type and payer. Two certified coders label each independently, then adjudicate with a senior coder. Keep notes de-identified where possible; if you need PHI, evaluate inside the compliant environment.
Measure code-level precision and recall, E/M exact agreement, modifier accuracy, evidence support and review time. Report by specialty and note type. A model strong on office visits and weak on operative reports can look acceptable overall and fail in surgery.
Denials are the next loop. Map CARC and RARC codes to the coding decision that caused them, then track overturn rate and root cause. A missing modifier may need a prompt, retrieval or workflow fix. Not every denial is a model error; some are documentation or eligibility problems.
HIPAA, BAA and cost
If the API processes PHI for a covered entity or business associate, a BAA is generally required. Verify that the specific plan, endpoint and subprocessors are covered, and that the BAA is signed before any PHI is sent. Retention, training, breach notice and audit terms belong in the contract.
Use minimum necessary data. Redact identifiers not needed for coding, restrict access, encrypt at rest and in transit, and log access. If the provider retains prompts, confirm that retention fits your policy and BAA. Counsel review is required; this page does not claim HIPAA compliance.
Token cost is small next to compliance work. At 3,000 input and 500 output tokens a note, 100 notes use about 300,000 input and 50,000 output tokens. Plugsky paid plans start at $8 per month, but a BAA and deployment may need a higher tier or private deployment; confirm eligibility in the contract before sending PHI.
FAQ
Can AI assign ICD-10 and CPT codes automatically?
It can suggest codes, but it should not submit them without a certified coder's review. Coding depends on documentation, payer rules, bundling edits and clinical judgment. The safe pattern is suggestion, evidence, confidence and human sign-off.
Does a medical coding API need a BAA?
If the API processes protected health information on behalf of a covered entity, a business associate agreement is generally required. Whether a specific plan or endpoint is covered depends on the contract. Verify the BAA, subprocessors and retention terms in writing before sending PHI.
How do I evaluate coding accuracy?
Use at least 100 notes stratified by specialty and note type, with two certified coders labelling each note and adjudicating disagreements. Measure code-level precision and recall, E/M level agreement, modifier accuracy, evidence support and review time. Report by specialty, not just overall.
Should the model memorise code descriptions?
No. Code sets change every year, and model memory goes stale. Retrieve the current ICD-10-CM, CPT and HCPCS files from the authoritative source, map to them, and validate every code against the active release.
What does it cost to code 100 notes?
At about 3,000 input and 500 output tokens per note, 100 notes use roughly 300,000 input and 50,000 output tokens. Token cost is small on a paid plan, but a BAA and a compliant deployment may require a higher tier; verify eligibility before sending PHI.
Reviewed 20 November 2026. Sources checked 20 November 2026: code-system descriptions against CMS ICD-10, AMA CPT and CMS HCPCS; privacy duties against HHS HIPAA. This page is not medical or billing advice, does not claim HIPAA compliance, and requires certified-coder and counsel review before production.