Quickstart & First Request

Get started with the Corti Medical Coding API

Completing this quickstart will get you a working code prediction response from the Corti Medical Coding API. You can then explore the full API and use cases from there.

Prerequisites

• A Corti Console account — sign up at the Corti Console to get started.
• An API client — your tenant name, clientId, and clientSecret are all found in your API client configuration. See Creating API clients to set one up.

1. Send a prediction request

   POST a clinical note to the code prediction endpoint. The system field determines which classification is applied.

   Your environment (eu or us) is set in your API client — see Creating API clients.

   Parameter	Type	Required	Description
   system	string[]	Yes	One or more coding systems. Up to 4 per request. See Coding Systems for all options and recommended pairings.
   context	object[]	Yes	The clinical input to code. Each item is a text string or a documentId referencing a document stored in Corti.
   filter	object	No	Restrict predictions to specific codes or categories. See Code Prediction for details.

   JavaScript

   npm install @corti/sdk
   # or
   yarn add @corti/sdk
   # or
   pnpm add @corti/sdk
   

   dotnet add package Corti.Sdk
   
   # Alternatively, in your .csproj:
   # <PackageReference Include="Corti.Sdk" Version="*" />
   

   JavaScript

   import { CortiClient } from "@corti/sdk";
   
   // Replace these with your values
   const CLIENT_ID = "<your-client-id>";
   const CLIENT_SECRET = "<your-client-secret>";
   const ENVIRONMENT = "<eu-or-us>";
   const TENANT = "<your-tenant-name>";
   
   const client = new CortiClient({
       environment: ENVIRONMENT,
       tenantName: TENANT,
       auth: {
           clientId: CLIENT_ID,
           clientSecret: CLIENT_SECRET,
       },
   });
   

   using Corti;
   
   // Replace these with your values
   const string CLIENT_ID = "<your-client-id>";
   const string CLIENT_SECRET = "<your-client-secret>";
   const string ENVIRONMENT = "<eu-or-us>";
   const string TENANT = "<your-tenant-name>";
   
   var client = new CortiClient(
       tenantName: TENANT,
       environment: ENVIRONMENT,
       auth: CortiClientAuth.ClientCredentials(
           clientId: CLIENT_ID,
           clientSecret: CLIENT_SECRET)
   );
   

   JavaScript

   const response = await client.codes.predict({
     system: ["icd10cm-inpatient"],
     context: [
       {
         type: "text",
         text: "Discharge Summary: 82-year-old male admitted with acute STEMI, treated with primary PCI to LAD with drug-eluting stent placement. Hospital course complicated by cardiogenic shock requiring vasopressors for 48 hours. Also managed acute on chronic systolic heart failure (EF 25%), type 2 diabetes with peripheral neuropathy, and stage 3 CKD. Discharged to skilled nursing facility on dual antiplatelet therapy, beta blocker, ACE inhibitor, and insulin.",
       },
     ],
   });
   

   var response = await client.Codes.PredictAsync(new CodesGeneralPredictRequest
   {
       System = [CommonCodingSystemEnum.Icd10CmInpatient],
       Context =
       [
           new CommonTextContext
           {
               Type = new CommonTextContext.TypeLiteral(),
               Text = "Discharge Summary: 82-year-old male admitted with acute STEMI, treated with primary PCI to LAD with drug-eluting stent placement. Hospital course complicated by cardiogenic shock requiring vasopressors for 48 hours. Also managed acute on chronic systolic heart failure (EF 25%), type 2 diabetes with peripheral neuropathy, and stage 3 CKD. Discharged to skilled nursing facility on dual antiplatelet therapy, beta blocker, ACE inhibitor, and insulin.",
           },
       ],
   });
   

   import requests
   
   # Replace these with your values
   ENVIRONMENT = "<eu-or-us>"
   TENANT = "<your-tenant-name>"
   TOKEN = "<your-access-token>"
   
   response = requests.post(
       f"https://api.{ENVIRONMENT}.corti.app/v2/tools/coding/",
       headers={
           "Authorization": f"Bearer {TOKEN}",
           "Tenant-Name": TENANT,
           "Content-Type": "application/json",
       },
       json={
           "system": ["icd10cm-inpatient"],
           "context": [
               {
                   "type": "text",
                   "text": "Discharge Summary: 82-year-old male admitted with acute STEMI, treated with primary PCI to LAD with drug-eluting stent placement. Hospital course complicated by cardiogenic shock requiring vasopressors for 48 hours. Also managed acute on chronic systolic heart failure (EF 25%), type 2 diabetes with peripheral neuropathy, and stage 3 CKD. Discharged to skilled nursing facility on dual antiplatelet therapy, beta blocker, ACE inhibitor, and insulin.",
               }
           ],
       },
   )
   response.raise_for_status()
   result = response.json()
   

   # Replace these with your values
   ENVIRONMENT="<eu-or-us>"
   TENANT="<your-tenant-name>"
   TOKEN="<your-access-token>"
   
   curl -X POST "https://api.${ENVIRONMENT}.corti.app/v2/tools/coding/" \
     -H "Authorization: Bearer ${TOKEN}" \
     -H "Tenant-Name: ${TENANT}" \
     -H "Content-Type: application/json" \
     -d '{
       "system": ["icd10cm-inpatient"],
       "context": [
         {
           "type": "text",
           "text": "Discharge Summary: 82-year-old male admitted with acute STEMI, treated with primary PCI to LAD with drug-eluting stent placement. Hospital course complicated by cardiogenic shock requiring vasopressors for 48 hours. Also managed acute on chronic systolic heart failure (EF 25%), type 2 diabetes with peripheral neuropathy, and stage 3 CKD. Discharged to skilled nursing facility on dual antiplatelet therapy, beta blocker, ACE inhibitor, and insulin."
         }
       ]
     }'
   

   The SDK handles OAuth 2.0 token acquisition and refresh automatically using your clientId and clientSecret — no need to manage bearer tokens manually.
2. Read the response

   A successful response returns three top-level fields:

   • codes — the model’s high-confidence predictions. Each entry includes the code, a human-readable display, evidences (the exact passages from the note that support the prediction, with contextIndex, text, and start/end character offsets), and alternatives (other codes the model considered for the same finding).
   • candidates — lower-confidence codes worth reviewing. Intended for coder review rather than automatic assignment.
   • usageInfo — credits consumed for this request.

   {
   "codes": [
   {
   "system": "icd10cm-outpatient",
   "code": "E11.649",
   "display": "Type 2 diabetes mellitus with hypoglycemia without coma",
   "evidences": [
   {
     "contextIndex": 0,
     "text": "occasional mild hypoglycemia",
     "start": 90,
     "end": 118
   }
   ],
   "alternatives": [
   {
     "code": "E11.65",
     "display": "Type 2 diabetes mellitus with hyperglycemia"
   }
   ]
   },
   {
   "system": "icd10cm-outpatient",
   "code": "M17.11",
   "display": "Primary osteoarthritis, right knee",
   "evidences": [
   {
     "contextIndex": 0,
     "text": "bilateral knee pain consistent with osteoarthritis",
     "start": 174,
     "end": 224
   }
   ]
   }
   ],
   "candidates": [
   {
   "system": "icd10cm-outpatient",
   "code": "Z79.4",
   "display": "Long-term (current) use of insulin"
   }
   ],
   "usageInfo": {
   "creditsConsumed": 1.5
   }
   }
   
3. Combine coding systems

   Most US encounters require more than one coding system. Pass multiple values in system — for example, pairing ICD-10-CM with CPT for an outpatient visit. The response includes codes from all requested systems in the same codes array, each tagged with its system value.

   JavaScript

   const response = await client.codes.predict({
     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.",
       },
     ],
   });
   

   var response = await client.Codes.PredictAsync(new CodesGeneralPredictRequest
   {
       System = [CommonCodingSystemEnum.Icd10CmOutpatient, CommonCodingSystemEnum.Cpt],
       Context =
       [
           new CommonTextContext
           {
               Type = new CommonTextContext.TypeLiteral(),
               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.",
           },
       ],
   });
   

   import requests
   
   # Replace these with your values
   ENVIRONMENT = "<eu-or-us>"
   TENANT = "<your-tenant-name>"
   TOKEN = "<your-access-token>"
   
   response = requests.post(
       f"https://api.{ENVIRONMENT}.corti.app/v2/tools/coding/",
       headers={
           "Authorization": f"Bearer {TOKEN}",
           "Tenant-Name": TENANT,
           "Content-Type": "application/json",
       },
       json={
           "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.",
               }
           ],
       },
   )
   response.raise_for_status()
   result = response.json()
   

   # Replace these with your values
   ENVIRONMENT="<eu-or-us>"
   TENANT="<your-tenant-name>"
   TOKEN="<your-access-token>"
   
   curl -X POST "https://api.${ENVIRONMENT}.corti.app/v2/tools/coding/" \
     -H "Authorization: Bearer ${TOKEN}" \
     -H "Tenant-Name: ${TENANT}" \
     -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."
         }
       ]
     }'
   

   See Coding Systems for recommended pairings by encounter type.

Next steps

Code Prediction

Learn about the endpoint, supported features, and coding system options.

How it works

Understand the request schema, response fields, evidence spans, and filtering options.

Use cases

Encounter coding, CDI review, HCC capture, and revenue cycle workflows.

Please contact us if you need help getting started or run into issues with your first request.