Skip to main content
The Code Prediction API converts unstructured clinical contexts (e.g., encounter notes, discharge summaries, transcripts) into structured medical codes. Every response contains two top-level lists, codes and candidates, each holding code objects with system, code, display, evidences, and alternatives.
Example codes response

​
One response, two lists of codes

Deciding whether a medical entity should be coded is a difficult and often subjective decision. Every diagnosis, symptom, or health context in a clinical note should not be coded. For instance, a symptom should only be coded if it is not commonly associated with one of the patient’s diagnoses. A chronic condition should only be coded if it affects patient care. Therefore, two lists are returned at the top level: codes and candidates:
  • codes contains the medical entities that the model confidently predicts should be coded.
  • candidates contains entities that are clinically relevant but not strictly required; optional codes that may warrant human review.
Recommendation: When building an interface for medical coding, include both lists but visualize their contents differently. Or, to present all codes indicated by a clinical note without concern for billing rules, then merge the two lists into one display.

​
Each code object

Each list contains several code objects. Each object represents one medical entity (condition, symptom, health context, medication, or procedure, depending on the coding system).
  • system is the coding system the code belongs to (e.g. icd10cm-outpatient, cpt).
  • code is the code that best describes the entity.
  • display is the name of that code (often called code description).
  • evidences contains all the spans of text where the medical entity is mentioned. Each evidence object includes contextIndex (the index of the context item in your request array), text (the relevant text snippet), and start/end (0-based character offsets into the context text, inclusive and exclusive respectively).
  • alternatives contains other codes that could also describe the medical entity — codes the system considered but deemed less relevant than the one in code.

​
Sequencing

For coding systems where order affects reimbursement (e.g., ICD-10-CM, ICD-10-GM, CIM-10-FR, NHS ICD-10), the API returns codes in the predicted sequence: principal diagnosis or principal procedure appears first, followed by secondary diagnoses and additional procedures in order of clinical significance. This allows the position of a code in the codes array to be used directly, without needing to re-sort the results; however, client-specific rules, payer constraints, regulatory guidelines, or other compliance requirements that are unknown to the code prediction model may not be factored in to sorting.
See the feature matrix for full details on sequencing availability per coding system.