Skip to main content
An implementation guide for product and engineering teams building encounter coding workflows using the Corti Medical Coding API. The most common use of the Medical Coding API is straightforward: take a clinical note, get back structured diagnosis and procedure codes, and route them for human review before submission. This page walks through the decisions, implementation patterns, and success metrics for building that workflow.

​
Before Building

Before writing integration code, align on the fundamentals:
The coding systems you request determine the type of codes returned. Getting this right is the most important configuration decision.Inpatient encounters (hospital admissions, observation stays) use:
  • icd10cm-inpatient for diagnosis codes
  • icd10pcs for procedure codes
Outpatient encounters (office visits, ED encounters, ambulatory surgery) use:
  • icd10cm-outpatient for diagnosis codes
  • cpt for procedure codes
International encounters use the WHO base classification or a national extension (e.g., icd10 for the WHO version, icd10gm for Germany). See Coding Systems for the full list.If your platform handles both inpatient and outpatient encounters, use encounter metadata (admission type, facility type, or department) to select the correct coding system at request time.
Decide how code suggestions flow through your system and who interacts with them:
  • Coder-in-the-loop: Route suggestions to a professional coder who confirms, rejects, or adjusts each code before submission. This is a common workflow in health systems with dedicated coding teams.
  • Physician-facing auto-suggest: Surface suggestions directly to the treating physician during or after documentation. This works well in smaller practices or outpatient settings where physicians code their own encounters.
  • Pre-populated worklist: Use API suggestions to pre-fill a coding worklist that coders then review in their existing coding tool.
  • Automated pipeline: Feed API output directly into downstream billing or analytics systems without manual review.
The codes list contains high-confidence predictions suitable for pre-population or automation. The candidates list contains clinically relevant but optional codes that benefit from human judgment — surface these as suggestions rather than defaults.
Encounter coding is most valuable when it sits inside existing workflows rather than as a standalone tool.Determine:
  • Where notes come from — Are you pulling finalized notes from an EHR, receiving them via HL7/FHIR, or generating them with Corti’s ambient documentation?
  • Where codes go — Do confirmed codes write back to the EHR, feed into a billing system, or populate a claim form?
  • When coding runs — Does it trigger automatically on note finalization, or does a coder manually initiate it?
Integration scope will heavily influence build complexity. A lightweight copy/paste workflow can be built in days. A fully embedded EHR integration with bi-directional write-back is a larger effort — but delivers significantly more value.

​
Success Metrics

Identifying the right metrics early helps you evaluate the integration and build confidence with clinical and revenue cycle stakeholders.
The primary measure of model quality is agreement with the final billed code set.Measure:
  • Agreement rate between API codes and final billed codes
  • False positive rate (API-suggested codes rejected by reviewers)
  • False negative rate (codes added by reviewers that the API missed)
Run a shadow period before go-live: process notes through the API without surfacing results, then compare against what coders submitted independently. This gives you a baseline accuracy number before changing any workflows.A high acceptance rate (above 80%) with stable accuracy indicates the model is adding genuine value. A low acceptance rate may indicate a mismatch between encounter types and coding system configuration.
If the API is working well, coders should be able to review more encounters per hour because they are confirming suggestions rather than coding from scratch.Measure:
  • Encounters coded per hour (before vs. after)
  • Average time per encounter
  • Percentage of API suggestions accepted without modification
Coding errors are a leading cause of claim denials. Better initial code suggestions should reduce denial rates over time.Measure:
  • Claim denial rate (before vs. after)
  • Denial reasons related to coding errors (incorrect code, missing modifier, insufficient specificity)
  • Rework rate for returned claims
This metric takes longer to materialize — typically 2-3 months after go-live — but is one of the strongest ROI indicators for revenue cycle leadership.
The elapsed time between note finalization and code submission reflects both coder efficiency and workflow friction.Measure:
  • Average time from note finalization to code submission
  • Backlog size (encounters awaiting coding)
Reducing time-to-code accelerates the revenue cycle and improves cash flow. It also reduces the cognitive burden on coders who otherwise need to re-read notes they may have seen days ago.

​
Implementation

​
Inpatient Encounter Workflow

For inpatient encounters, you typically need both diagnosis and procedure codes. This requires two API calls — one for each coding system. 
curl -X POST https://api.eu.corti.app/v2/tools/coding/ \
  -H "Authorization: Bearer <token>" \
  -H "Tenant-Name: <tenant-name>" \
  -H "Content-Type: application/json" \
  -d '{
    "system": ["icd10cm-inpatient"],
    "context": [
      {
        "type": "text",
        "text": "Discharge Summary: 72-year-old female admitted with acute exacerbation of COPD and community-acquired pneumonia. Treated with IV antibiotics and bronchodilators. Intubated on day 2 for respiratory failure, extubated day 5. Also managed type 2 diabetes with insulin sliding scale. Discharged on oral antibiotics and home oxygen."
      }
    ]
  }'

​
Outpatient Encounter Workflow

For outpatient encounters, diagnosis and procedure codes can be requested in a single call. 
curl -X POST https://api.eu.corti.app/v2/tools/coding/ \
  -H "Authorization: Bearer <token>" \
  -H "Tenant-Name: <tenant-name>" \
  -H "Content-Type: application/json" \
  -d '{
    "system": ["icd10cm-outpatient", "cpt"],
    "context": [
      {
        "type": "text",
        "text": "Subjective: 58-year-old male presents for routine diabetes management. HbA1c is 7.2%. Reports occasional mild hypoglycemia. Currently on metformin 1000mg twice daily. Also notes bilateral knee pain worsening over past 3 months.\n\nAssessment and Plan: 1. Type 2 diabetes mellitus — well controlled on current regimen, continue metformin, recheck HbA1c in 3 months. 2. Bilateral knee osteoarthritis — refer to orthopedics, start topical diclofenac. 3. Hypoglycemia episodes — counseled on timing of meals relative to medication."
      }
    ]
  }'

​
Using Evidence Spans

Every code in the response includes evidences — references pointing back to the context that drove the prediction. Use these to build trust in the review workflow. 
{
  "system": "icd10cm-inpatient",
  "code": "J441",
  "display": "Chronic obstructive pulmonary disease with (acute) exacerbation",
  "evidences": [
    {
      "contextIndex": 0,
      "text": "acute exacerbation of COPD",
      "start": 52,
      "end": 78
    }
  ]
}
In your review interface:
  • Highlight the evidence span in the original note when a coder hovers or selects a code
  • Let coders see at a glance why the model suggested each code
  • Use evidence spans to speed up the confirm/reject decision — coders can validate the suggestion without re-reading the full note

​
Input Formats

The context field accepts an array of context objects. You can pass multiple context items to provide the model with more clinical information. See How it works for details on the request schema.

​
Tying It All Together

Encounter diagnosis coding is the foundation that other medical coding workflows build on. Once you have a working integration: Start with a single encounter type (inpatient or outpatient), run a shadow period to establish your accuracy baseline, and expand from there.
Please contact us if you need help setting up your encounter coding workflow or have questions about coding system selection.