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

# E/M Coding APIs Overview

> Generate Evaluation and Management codes from note content for revenue cycle workflows with standalone E/M Coding APIs

**Are you a Suki partner?**

To use any Suki API or SDK, you must be a Suki partner. Contact the partnership team to begin the onboarding process. They help you set up your authentication system and get started with the Suki APIs and SDKs.

[Contact Partnership Team](https://www.suki.ai/contact-us/)

> [!NOTE]
>
> * E/M Coding is in **Beta**. Behavior and response fields can change based on user feedback.
> * E/M Coding must be enabled for your organization. If you are unsure whether it is enabled, contact the [Partnership team](https://www.suki.ai/contact-us/).

Suki's E/M Coding APIs let you generate Evaluation and Management (E/M) code recommendations from a completed clinical note. The APIs help you integrate E/M coding into your revenue cycle management (RCM) workflows.

To request E/M codes, send the note sections along with any available patient, provider, encounter, and diagnosis context. Suki processes the request asynchronously and returns recommended codes with supporting information, such as medical decision making (MDM), time-based, or wellness coding, when available.

You can generate E/M codes in either of two ways:

* **From an ambient session:** Your application already uses Ambient, and Suki writes the note. Enable E/M Coding on that visit so the recommended code comes back with the note. Refer to [Choose Ambient or standalone](https://developer.suki.ai/documentation/concepts/em-coding/choose-ambient-or-standalone.md).
* **From a completed note:** Use the standalone E/M Coding APIs to submit an existing note. You **do not** need an ambient session for this method.

Use the standalone E/M Coding APIs when you already have a completed clinical note for the visit. Submit the note, wait for code generation to finish, then retrieve the recommended E/M codes. This workflow does not require an ambient session, Form filling, or Dictation.

> [!NOTE]
>
> If you generate the note through an ambient session, request E/M codes as part of that workflow instead. Suki returns the codes with the note, so you do not need to call the standalone generation API for the same visit. Refer to [Add E/M codes to an ambient visit](https://developer.suki.ai/documentation/how-to/em-coding/generate-with-ambient.md) for more information.

Most operations use REST (Representational State Transfer. A software architectural style used for building web services.) APIs and return standard [HTTP status codes](https://developer.suki.ai/api-reference/https-guidelines.md). Generation is asynchronous. After you submit a request, poll the session status and retrieve the generated codes, or configure a webhook (HTTP callbacks sent to your service for asynchronous events and status updates.) to receive completion notifications.

## Available APIs

The following set of APIs are available for the standalone E/M Coding workflow. View each card below to learn about the endpoints and how to use them.

> [card] [Authentication](https://developer.suki.ai/em-coding-api-reference/authentication.md)
>
> Endpoints to authenticate and obtain tokens used to authorize E/M Coding API requests.

> [card] [Session Management](https://developer.suki.ai/em-coding-api-reference/em-coding-session-management.md)
>
> Endpoints to start a standalone E/M coding session, poll status, and retrieve generated codes.

> [card] [Notifications](https://developer.suki.ai/em-coding-api-reference/em-coding-notifications.md)
>
> Webhook specification for asynchronous standalone E/M coding session completion and failure.

## Authentication

For an overview of Suki's supported authentication mechanisms, refer to [Authentication mechanisms](https://developer.suki.ai/documentation/how-to/partner-authentication.md). We recommend using OAuth 2.0 with JWT tokens for your authentication system.

If you know what your authentication model is, refer to the following guides to get started:

> [card] [Single Auth Token Authentication](https://developer.suki.ai/api-reference/single-auth-token-authentication.md)

> [card] [Standard Provider Authentication](https://developer.suki.ai/api-reference/provider-authentication.md)

> [card] [Bearer Partner Authentication](https://developer.suki.ai/api-reference/bearer-partner-authentication.md)

Standalone E/M Coding requests use the same `sdp_suki_token` header pattern as other Partner APIs. Single Auth partners also send `sdp_provider_id` when required.

## Key capabilities

The E/M Coding APIs let you generate a recommended E/M code and show it to a reviewer before your application sends the accepted code to billing or the EHR.

> [card] Standalone Code Generation
>
> Submit note sections and optional context to start an asynchronous coding session without an ambient session or audio stream.

> [card] Asynchronous Processing
>
> Poll coding status until completion, or receive a webhook when the standalone session finishes or fails.

> [card] Structured Code Output
>
> Read the recommended E/M code, whether the patient is new or established, the level, and the reason, which is medical decision making, time, or a wellness visit.

> [card] Ambient-Attached Coding
>
> Your application already uses Ambient to document the visit. Enable E/M Coding when you create the session with `artifacts: ["EM_CODES"]`, add the patient and visit details, and read the recommended code with the note.

> [card] Webhook Notifications
>
> Receive standalone E/M completion events with `session_type` set to `EM_CODES`, including links to status and code retrieval.

> [card] Partner-Owned Handoff
>
> Show the code and the reason, let a reviewer accept it or choose a different code, then pass the accepted code into your billing workflow. Suki does not submit the claim or update the EHR.

## Requirements

Before you can use the E/M Coding APIs, you need to meet the following requirements:

* You must be a Suki partner. Learn more about how to become a Suki partner in the [Partner onboarding](https://developer.suki.ai/documentation/get-started/partner-onboarding.md) documentation.
* A standards-based authentication system (for example OAuth 2.0 or OpenID Connect with JWTs) and a working Login path to obtain an `sdp_suki_token`.
* E/M Coding enabled for your organization.
* For standalone coding: note sections, each with a LOINC code and the section text. Patient, visit, and diagnosis details are optional, and [Provide existing diagnoses](https://developer.suki.ai/documentation/concepts/em-coding/overview.md#provide-existing-diagnoses) explains which diagnosis types to send.
* For E/M Coding with Ambient: an Ambient integration that can create a session, add the patient and visit details, and read the codes with the note.

## What you can build

Use the E/M Coding APIs when the note is finished and you need a recommended E/M code for someone to review, often the clinician who just finished the note, or a coding team if that is how your application routes it, and show the code and the reason so that person can accept it or choose a different code before your application sends anything to billing.

You can align E/M Coding with:

* Ambient note completion for the same visit.
* RCM backends that already store note text and diagnoses.
* Time-based or wellness visit coding when you send the supporting context.
* Coding review UI before payer or EHR submission.

Implement your own logic for session start, status polling or webhooks, code review, and downstream handoff using the standalone E/M Coding REST APIs. For E/M Coding with Ambient, see [E/M Coding overview](https://developer.suki.ai/documentation/concepts/em-coding/overview.md).

### Common use cases

> [card] Code an Existing Note
>
> The note is already in your application, so submit the note sections, and any diagnoses you already have, with `POST /api/v1/em-codes`, and when coding finishes, read the recommended E/M code.

> [card] Attach Codes to Ambient Visits
>
> Your application already uses Ambient to document the visit. Enable E/M Coding when you create the session with `artifacts: ["EM_CODES"]`, add the patient and visit details, and read the recommended code with the note.

> [card] Feed Coding Review Queues
>
> Show the E/M code first, with the level, whether the patient is new or established, and the reason beside it. The reviewer accepts that code or chooses a different one, and your application sends only the accepted code to billing.

[View All Use Cases](https://developer.suki.ai/documentation/get-started/use-case.md?workflow=em-coding)

## API versioning

All endpoints use the `/api/v1/` prefix. **v1** is the stable version. Non-breaking changes may ship without a major version jump. For policies and migration, refer to [API guidelines](https://developer.suki.ai/api-reference/api-guidelines.md).

## Suki E/M Coding APIs workflow

To integrate with the standalone E/M Coding APIs, you follow a session-based generate, poll, and retrieve workflow.

![Flowchart: Yes, No, Yes completed, Yes failed, Start integration, Authenticate and obtain tokens, POST /api/v1/em-codes, Get E/M coding session\_id, Webhook configured?, Receive E/M notification, GET /api/v1/em-codes/session\_id/status, Terminal status?, GET /api/v1/em-codes/session\_id, Handle failed session, Workflow complete.](https://mintcdn.com/suki-1e08f176/pF0w94HUbC96pJHg/documentation/assets/diagrams/em-coding-api-reference-overview-1-light.svg?fit=max\&auto=format\&n=pF0w94HUbC96pJHg\&q=85\&s=fcbda3aaa0dfd1c23e836762e6f57d41)

```mermaid actions={false} theme={"theme":{"light":"one-light","dark":"material-theme-darker"}}
flowchart TD
  Start([Start integration]) --> Auth[Authenticate and obtain tokens]
  Auth --> Generate["POST /api/v1/em-codes"]
  Generate --> SessionID[Get E/M coding session_id]
  SessionID --> Notify{Webhook configured?}
  Notify -->|Yes| Hook[Receive E/M notification]
  Notify -->|No| Poll["GET /api/v1/em-codes/session_id/status"]
  Hook --> Poll
  Poll --> Terminal{Terminal status?}
  Terminal -->|No| Poll
  Terminal -->|Yes completed| Retrieve["GET /api/v1/em-codes/session_id"]
  Terminal -->|Yes failed| Failed[Handle failed session]
  Retrieve --> Complete([Workflow complete])
  Failed --> Complete

  classDef authStyle fill:#FFE148,stroke:#D4A017,stroke-width:2px,color:#000000
  classDef highlightStyle fill:#FFD700,stroke:#D4A017,stroke-width:3px,color:#000000

  class Auth,Generate,Poll,Retrieve authStyle
  class Complete highlightStyle
```

### Developer workflow

**1. Authenticate and Obtain Tokens**

Authenticate using Login or Register to obtain your `sdp_suki_token`. Use that token on every standalone E/M Coding request.

**2. Start Coding**

Call `POST /api/v1/em-codes` with note `sections` (required) and optional patient, provider, encounter, and diagnoses context, and Suki returns an E/M `session_id`, which is not an ambient session ID.

**3. Wait for Completion**

Poll `GET /api/v1/em-codes/{session_id}/status` until `completed` or `failed`, or wait for the standalone E/M webhook when configured.

**4. Retrieve Codes**

Call `GET /api/v1/em-codes/{session_id}`, show the code and the reason from `em_codes.values`, let a reviewer accept the code or choose a different one, and then send the accepted code into your billing workflow.

> [!NOTE]
>
> If webhooks are enabled for your partner account, your application can receive automatic completion notifications instead of relying only on polling.

> [!TIP]
>
> **Best practices**
>
> * Store authentication credentials securely and rotate per your security policy.
> * Send ICD-10 or IMO on `diagnoses`, since those are the problem codes Suki uses with the note when it recommends the E/M code, and you can include SNOMED on the same list even though Suki does not use it for that recommendation. Do not send HCC, because that type is not accepted and the diagnosis fails validation.
> * Send `total_time_minutes` when you bill by time, and only when the value is greater than 0.
> * Use `YYYY-MM-DD` for `dob` and `date_of_service`, and do not send future dates.
> * Retrieve codes within 30 days, because after that retrieve returns a retention error.
> * When you generate E/M codes with an ambient session, a coding skip or failure does not fail the ambient note job, and empty `em_codes.values` means no recommendation.
> * Match validation messages from [E/M Coding error messages](https://developer.suki.ai/em-coding-api-reference/error-messages-em-coding.md) by exact text or prefix.

## Resources

Refer to the following resources to learn about security, HTTPS requirements, and API guidelines.

> [card] [Security & Best Practices](https://developer.suki.ai/api-reference/security-best-practices.md)
>
> Review token handling, transport security, and partner integration safeguards.

> [card] [HTTPS Guidelines](https://developer.suki.ai/api-reference/https-guidelines.md)
>
> Confirm TLS, headers, and HTTPS requirements for API and WebSocket traffic.

> [card] [API Reference Guidelines](https://developer.suki.ai/api-reference/api-guidelines.md)
>
> Read versioning, error handling, and REST conventions for Suki APIs.

## Next steps

 **[E/M Coding API quickstart](https://developer.suki.ai/em-coding-api-reference/quickstart.md)** - Get started.


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