> ## Documentation Index
> Fetch the complete documentation index at: https://developer.suki.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Generate E/M Codes

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

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](https://developer.suki.ai/em-coding-api-reference/em-coding-sessions/status.md), then retrieve the results with [Get E/M codes](https://developer.suki.ai/em-coding-api-reference/em-coding-sessions/get.md). If you have configured a [Webhook](https://developer.suki.ai/em-coding-api-reference/asynchronous/webhook.md), 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.

> [!NOTE]
>
> 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.

> [!TIP]
>
> To generate E/M codes as part of an ambient visit, pass `artifacts: ["EM_CODES"]` to [Create ambient session](https://developer.suki.ai/api-reference/ambient-sessions/create.md) instead. See [Add E/M codes to an ambient visit](https://developer.suki.ai/documentation/how-to/em-coding/generate-with-ambient.md).

## 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

> [!NOTE]
>
> 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](https://developer.suki.ai/api-reference/api-guidelines.md#using-code-examples-in-your-integration) in the **API Reference Guidelines**.

**Language tabs (agents):** Equivalent code samples are available in: Python, TypeScript. Humans see one language at a time. Use the variant that matches the user's stack; behavior is the same across tabs.

> [tab] Python
>
> ```python expandable theme={"theme":{"light":"one-light","dark":"material-theme-darker"}}
> 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())
> ```

> [tab] TypeScript
>
> ```typescript expandable theme={"theme":{"light":"one-light","dark":"material-theme-darker"}}
> 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());
> ```


## OpenAPI

````yaml POST /api/v1/em-codes
openapi: 3.0.1
info:
  title: Suki Developer Platform
  description: >-
    REST and WebSocket APIs for the Suki Developer Platform. Authenticate with
    Login or Register to obtain a Suki access token, then integrate ambient
    clinical documentation, form filling, transcription, content rewrite, and
    reference metadata endpoints.
  contact: {}
  version: '1.0'
servers:
  - url: https://sdp.suki.ai
    description: >-
      Production base URL for Suki Developer Platform REST APIs. WebSocket
      endpoints use the same host with `wss://`.
security:
  - SukiTokenAuth: []
paths:
  /api/v1/em-codes:
    post:
      tags:
        - /api/v1/em-codes
      summary: Generates E/M codes for a note, outside of an ambient session.
      description: >-
        Starts a standalone E/M coding session for partner-supplied note content
        and returns its session_id. Sections are the only required input and at
        least one must carry content text; patient, provider, encounter and
        diagnoses are optional and improve code selection. Generation is
        asynchronous; poll the status endpoint and then read the codes.
      parameters:
        - $ref: '#/components/parameters/ProviderIdHeader'
      requestBody:
        required: true
        description: >-
          Note sections and optional patient, provider, encounter, and diagnosis
          context for standalone E/M code generation.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/controllers.GenerateEMCodesRequest'
      responses:
        '201':
          description: Success Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/controllers.GenerateEMCodesResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/controllers.BadRequestError'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/controllers.AuthenticationError'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/controllers.InternalServerError'
      security:
        - SukiTokenAuth: []
components:
  parameters:
    ProviderIdHeader:
      name: sdp_provider_id
      in: header
      description: >-
        **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`.
      required: false
      schema:
        type: string
        example: provider-123
  schemas:
    controllers.GenerateEMCodesRequest:
      type: object
      required:
        - sections
      properties:
        diagnoses:
          description: (Optional) Diagnoses for the encounter.
          allOf:
            - $ref: '#/components/schemas/controllers.DiagnosesContext'
        encounter:
          description: (Optional)
          allOf:
            - $ref: '#/components/schemas/controllers.EMEncounterInput'
        patient:
          description: (Optional)
          allOf:
            - $ref: '#/components/schemas/controllers.EMPatientInput'
        provider:
          description: (Optional)
          allOf:
            - $ref: '#/components/schemas/controllers.EMProviderInput'
        sections:
          description: Note sections to code from; at least one must carry content text.
          type: array
          items:
            $ref: '#/components/schemas/controllers.EMSections'
    controllers.GenerateEMCodesResponse:
      type: object
      properties:
        session_id:
          description: E/M coding session ID; use for the status and retrieval APIs.
          type: string
          example: 123dfg-456dfg-789dfg-012dfg
    controllers.BadRequestError:
      description: Bad Request Response
      type: object
      properties:
        code:
          type: integer
          example: 400
        message:
          type: string
          example: invalid request
    controllers.AuthenticationError:
      description: Authentication Failure Response
      type: object
      properties:
        code:
          type: integer
          example: 401
        message:
          type: string
          example: invalid token
    controllers.InternalServerError:
      description: Internal Server Error Response
      type: object
      properties:
        code:
          type: integer
          example: 500
        message:
          type: string
          example: internal server error
    controllers.DiagnosesContext:
      type: object
      properties:
        values:
          description: (Optional) Array of diagnosis requests
          type: array
          items:
            $ref: '#/components/schemas/controllers.DiagnosisRequest'
    controllers.EMEncounterInput:
      description: Encounter details submitted for standalone E/M generation
      type: object
      properties:
        csn:
          description: (Optional) Contact Serial Number, up to 64 characters.
          type: string
          example: CSN-12345
        date_of_service:
          description: (Optional) {YYYY-MM-DD}, not in the future.
          type: string
          example: '2026-01-01'
        total_time_minutes:
          description: (Optional) Total clinician time in minutes, greater than 0.
          type: integer
          example: 35
        visit_type:
          description: (Optional)
          type: string
          example: ESTABLISHED_PATIENT
    controllers.EMPatientInput:
      description: Patient details submitted for standalone E/M generation
      type: object
      properties:
        dob:
          description: (Optional) {YYYY-MM-DD}, not in the future.
          type: string
          example: '2000-01-01'
        insurance:
          description: (Optional)
          allOf:
            - $ref: '#/components/schemas/controllers.EMInsuranceInfo'
        mrn:
          description: (Optional) Patient medical record number, up to 64 characters.
          type: string
          example: MRN-12345
        patient_type:
          description: (Optional)
          type: string
          enum:
            - NEW_PATIENT
            - ESTABLISHED_PATIENT
          example: ESTABLISHED_PATIENT
        sex:
          description: (Optional)
          type: string
          enum:
            - male
            - female
            - other
            - unknown
          example: male
    controllers.EMProviderInput:
      description: Provider details submitted for standalone E/M generation
      type: object
      properties:
        first_name:
          description: (Optional)
          type: string
          example: Jane
        last_name:
          description: (Optional)
          type: string
          example: Doe
        npi:
          description: (Optional) National Provider Identifier, up to 64 characters.
          type: string
          example: '1234567893'
        speciality:
          description: (Optional)
          type: string
          example: CARDIOLOGY
    controllers.EMSections:
      description: A note section submitted for standalone E/M generation
      type: object
      required:
        - content
        - loinc
      properties:
        content:
          description: Section content.
          allOf:
            - $ref: '#/components/schemas/controllers.EMContent'
        loinc:
          description: LOINC code identifying the section.
          type: string
          example: 10164-2
    controllers.DiagnosisRequest:
      type: object
      properties:
        codes:
          type: array
          description: >-
            **Optional** - Codes associated with the diagnosis. When sending
            context, use ICD10 or IMO. HCC codes are returned in structured data
            output only.
          items:
            $ref: '#/components/schemas/controllers.Code'
        diagnosis_note:
          type: string
          description: '**Optional** - Diagnosis note'
          example: Hypertension
    controllers.EMInsuranceInfo:
      description: Insurance coverages used for E/M coding
      type: object
      properties:
        coverages:
          type: array
          items:
            $ref: '#/components/schemas/controllers.EMInsuranceCoverage'
    controllers.EMContent:
      description: Content of a note section submitted for standalone E/M generation
      type: object
      properties:
        text:
          description: (Optional) Section text.
          type: string
          example: Patient presents with headache.
        type:
          description: (Optional) Content type; TEXT is the only supported value.
          type: string
          enum:
            - TEXT
          example: TEXT
    controllers.Code:
      type: object
      properties:
        code:
          description: Code value
          type: string
          example: '30422'
        description:
          description: Description of the code
          type: string
          example: Essential hypertension
        type:
          type: string
          enum:
            - UNSPECIFIED
            - IMO
            - ICD10
            - SNOMED
          example: IMO
    controllers.EMInsuranceCoverage:
      description: A single insurance coverage, as provided by the EMR
      type: object
      properties:
        eligibility_status:
          description: (Optional) Eligibility status.
          type: string
          example: Eligible
        insurance_payer_name_raw:
          description: (Optional) Raw payer name.
          type: string
          example: AETNA
        insurance_product_type_raw:
          description: (Optional) Raw insurance product type.
          type: string
          example: PPO
        insurance_type_raw:
          description: (Optional) Raw insurance type.
          type: string
          example: Commercial
        sequence_number:
          description: (Optional) "1" for primary, "2" for secondary, etc.
          type: string
          example: '1'
  securitySchemes:
    SukiTokenAuth:
      type: apiKey
      in: header
      name: sdp_suki_token
      description: >-
        Suki access token (`suki_token`) from Login or Register. Expires after
        one hour.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.