Skip to main content
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.
  • 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.
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.
  • 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.
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 for more information.
Most operations use APIs and return standard HTTP status codes. Generation is asynchronous. After you submit a request, poll the session status and retrieve the generated codes, or configure a 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.

Authentication

Endpoints to authenticate and obtain tokens used to authorize E/M Coding API requests.

Session Management

Endpoints to start a standalone E/M coding session, poll status, and retrieve generated codes.

Notifications

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

Single Auth Token Authentication

Standard Provider Authentication

Bearer Partner Authentication

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.

Standalone Code Generation

Submit note sections and optional context to start an asynchronous coding session without an ambient session or audio stream.

Asynchronous Processing

Poll coding status until completion, or receive a webhook when the standalone session finishes or fails.

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.

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.

Webhook Notifications

Receive standalone E/M completion events with session_type set to EM_CODES, including links to status and code retrieval.

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

​
Common use cases

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.

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.

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.

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

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

​
Developer workflow

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.

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.

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.

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.
If webhooks are enabled for your partner account, your application can receive automatic completion notifications instead of relying only on polling.
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 by exact text or prefix.

​
Resources

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

Security & Best Practices

Review token handling, transport security, and partner integration safeguards.

HTTPS Guidelines

Confirm TLS, headers, and HTTPS requirements for API and WebSocket traffic.

API Reference Guidelines

Read versioning, error handling, and REST conventions for Suki APIs.

​
Next steps

E/M Coding API quickstart - Get started.
Last modified on November 5, 2026