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. 
{
  "codes": [
    {
      "system": "icd10cm-outpatient",
      "code": "E11649",
      "display": "Type 2 diabetes mellitus with hypoglycemia without coma",
      "evidences": [{ "contextIndex": 0, "text": "occasional mild hypoglycemia", "start": 90, "end": 118 }],
      "alternatives": [{ "code": "E1165", "display": "Type 2 diabetes mellitus with hyperglycemia" }]
    }
  ],
  "candidates": [
    {
      "system": "icd10cm-outpatient",
      "code": "Z794",
      "display": "Long-term (current) use of insulin",
      "evidences": [...],
      "alternatives": [...]
    }
  ]
}

​
The top level

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.
Please contact us if you have questions about the response structure or need help interpreting code predictions.