Generate E/M Codes

Start a standalone E/M coding session from partner-supplied note sections and optional clinical context

POST /api/v1/em-codes

Generates E/M codes for a note, outside of an ambient session.

cURL

curl --request POST \
  --url https://sdp.suki.ai/api/v1/em-codes \
  --header 'Content-Type: application/json' \
  --header 'sdp_suki_token: <api-key>' \
  --data '
{
  "sections": [
    {
      "content": {
        "text": "Patient presents with headache.",
        "type": "TEXT"
      },
      "loinc": "10164-2"
    }
  ],
  "diagnoses": {
    "values": [
      {
        "codes": [
          {
            "code": "30422",
            "description": "Essential hypertension",
            "type": "IMO"
          }
        ],
        "diagnosis_note": "Hypertension"
      }
    ]
  },
  "encounter": {
    "csn": "CSN-12345",
    "date_of_service": "2026-01-01",
    "total_time_minutes": 35,
    "visit_type": "ESTABLISHED_PATIENT"
  },
  "patient": {
    "dob": "2000-01-01",
    "insurance": {
      "coverages": [
        {
          "eligibility_status": "Eligible",
          "insurance_payer_name_raw": "AETNA",
          "insurance_product_type_raw": "PPO",
          "insurance_type_raw": "Commercial",
          "sequence_number": "1"
        }
      ]
    },
    "mrn": "MRN-12345",
    "patient_type": "ESTABLISHED_PATIENT",
    "sex": "male"
  },
  "provider": {
    "first_name": "Jane",
    "last_name": "Doe",
    "npi": "1234567893",
    "speciality": "CARDIOLOGY"
  }
}
'

201

{
  "session_id": "123dfg-456dfg-789dfg-012dfg"
}

Use this API to start a standalone E/M coding session with clinical note content from your application. Send the note sections you have, and Suki returns an E/M coding session_id.

E/M code generation runs asynchronously. Check the status using Get E/M coding status, then retrieve the results with Get E/M codes. If you have configured a Webhook, you can receive a notification when generation completes instead.

The sections field is required and must contain at least one section with text, while patient, provider, encounter, and diagnoses details are optional. A diagnosis is a problem already on the chart, so when you send ICD-10 or IMO, Suki uses that problem together with the note when it recommends the E/M code.

The returned session_id identifies an E/M coding session, not an ambient session. Use it only with the E/M coding status and retrieval endpoints.

To generate E/M codes as part of an ambient visit, pass artifacts: ["EM_CODES"] to Create ambient session instead. See Add E/M codes to an ambient visit.

​

Request body fields

Field	Type	Details
sections	array	Required Note sections to code from. Each item needs loinc and content. At least one section must carry text. content.type supports TEXT only.
patient	object	Optional dob (YYYY-MM-DD), sex, patient_type (NEW_PATIENT / ESTABLISHED_PATIENT), mrn (up to 64 characters), and insurance.coverages[].
provider	object	Optional first_name, last_name, npi (up to 64 characters), and speciality.
encounter	object	Optional date_of_service (YYYY-MM-DD, not in the future), total_time_minutes (greater than 0 for time-based coding), csn (up to 64 characters), and visit_type.
diagnoses	object	Optional Problems already on the chart, as values[] with one code and a description, where Suki uses ICD-10 and IMO with the note when it recommends the E/M code, accepts SNOMED without using it, and rejects HCC because that type is not valid.

​

Code examples

The code examples below use placeholders and the production host sdp.suki.ai only as examples. For credentials, base URLs, where to run Python or TypeScript, CORS, and cURL, refer to Using code examples in your integration in the API Reference Guidelines.

Python

import json
import requests

BASE_URL = "https://sdp.suki.ai"
url = f"{BASE_URL}/api/v1/em-codes"

headers = {
    "sdp_suki_token": "<sdp_suki_token>",
    "sdp_provider_id": "<sdp_provider_id>",  # required for single_auth partners
    "Content-Type": "application/json",
}

payload = {
    "sections": [
        {
            "loinc": "10164-2",
            "content": {
                "type": "TEXT",
                "text": "Patient presents with headache. Continues lisinopril for hypertension.",
            },
        }
    ],
    "patient": {
        "dob": "1952-03-15",
        "sex": "female",
        "patient_type": "ESTABLISHED_PATIENT",
        "mrn": "MRN-12345",
        "insurance": {
            "coverages": [
                {
                    "sequence_number": "1",
                    "insurance_type_raw": "Commercial",
                    "insurance_product_type_raw": "PPO",
                    "insurance_payer_name_raw": "AETNA",
                    "eligibility_status": "Eligible",
                }
            ]
        },
    },
    "provider": {
        "first_name": "Jane",
        "last_name": "Doe",
        "npi": "1234567893",
        "speciality": "INTERNAL_MEDICINE",
    },
    "encounter": {
        "date_of_service": "2026-01-15",
        "total_time_minutes": 35,
        "visit_type": "ESTABLISHED_PATIENT",
        "csn": "CSN-12345",
    },
    "diagnoses": {
        "values": [
            {
                "codes": [
                    {
                        "type": "ICD10",
                        "code": "I10",
                        "description": "Essential (primary) hypertension",
                    }
                ]
            }
        ]
    },
}

response = requests.post(url, headers=headers, data=json.dumps(payload))
print(response.status_code)
print(response.json())

TypeScript

const BASE_URL = "https://sdp.suki.ai";
const url = `${BASE_URL}/api/v1/em-codes`;

const headers: Record<string, string> = {
  sdp_suki_token: "<sdp_suki_token>",
  sdp_provider_id: "<sdp_provider_id>", // required for single_auth partners
  "Content-Type": "application/json",
};

const payload = {
  sections: [
    {
      loinc: "10164-2",
      content: {
        type: "TEXT",
        text: "Patient presents with headache. Continues lisinopril for hypertension.",
      },
    },
  ],
  patient: {
    dob: "1952-03-15",
    sex: "female",
    patient_type: "ESTABLISHED_PATIENT",
    mrn: "MRN-12345",
    insurance: {
      coverages: [
        {
          sequence_number: "1",
          insurance_type_raw: "Commercial",
          insurance_product_type_raw: "PPO",
          insurance_payer_name_raw: "AETNA",
          eligibility_status: "Eligible",
        },
      ],
    },
  },
  provider: {
    first_name: "Jane",
    last_name: "Doe",
    npi: "1234567893",
    speciality: "INTERNAL_MEDICINE",
  },
  encounter: {
    date_of_service: "2026-01-15",
    total_time_minutes: 35,
    visit_type: "ESTABLISHED_PATIENT",
    csn: "CSN-12345",
  },
  diagnoses: {
    values: [
      {
        codes: [
          {
            type: "ICD10",
            code: "I10",
            description: "Essential (primary) hypertension",
          },
        ],
      },
    ],
  },
};

const response = await fetch(url, {
  method: "POST",
  headers,
  body: JSON.stringify(payload),
});
console.log(response.status, await response.json());

Authorizations

sdp_suki_token · string · header · required

Suki access token (suki_token) from Login or Register. Expires after one hour.

Headers

sdp_provider_id · string

Optional for standard partners.

Required for:

• Bearer authentication. Use the same provider_id returned by the Login or Register API.
• Single Auth Token authentication. Include the same provider_id on every request as sdp_provider_id.

Example:

"provider-123"

Body

application/json

Note sections and optional patient, provider, encounter, and diagnosis context for standalone E/M code generation.

sections · object[] · required

Note sections to code from; at least one must carry content text.

Show child attributes

diagnoses · object

(Optional) Diagnoses for the encounter.

Show child attributes

encounter · object

(Optional)

Show child attributes

patient · object

(Optional)

Show child attributes

provider · object

(Optional)

Show child attributes

Response

201

application/json

Success Response

session_id · string

E/M coding session ID; use for the status and retrieval APIs.

Example:

"123dfg-456dfg-789dfg-012dfg"