Skip to main content
Use the standalone E/M Coding APIs when your application or EHR creates the clinical note. Once the note is complete, call Generate E/M codes with the note sections and visit details. Suki analyzes the note and visit details to recommend Evaluation and Management (E/M) codes based on the services documented for the encounter.
The standalone E/M Coding APIs do not create or modify clinical notes. Suki bases its recommendations on the documentation you submit and does not infer services that are not recorded in the note.
The response includes a session_id that identifies the coding request. Store this ID with the encounter and use it to check the processing status and retrieve the recommended codes when processing is complete, passing the coding session_id to these endpoints rather than an ambient session ID. If Suki generates the clinical note from the clinician-patient conversation, enable E/M Coding on the ambient session instead. Suki returns the recommended codes with the completed note. Do not submit the same encounter through the standalone APIs. See Add E/M codes to an ambient visit.

Prerequisites

  • A Suki Token from Login. Refer to Partner authentication guide to learn more.
  • E/M Coding enabled for your organization. Contact support if you are unsure.
  • At least one note section with a LOINC code and the section text.

Steps to generate E/M codes from a note

1

Authenticate

Call Login, and Register once if this user is new. Send the returned token as sdp_suki_token on every E/M Coding request. If your partnership uses a Provider ID on each call, send sdp_provider_id as well.
2

Submit the Note

POST the completed note to /api/v1/em-codes, and Suki starts coding recommendations after this call returns. The generated response does not include the recommended codes.

Request body

Send the finished note in sections. Add patient, provider, encounter, and diagnoses when your EHR already has them, since those fields are optional and an ICD-10 or IMO diagnosis is a problem Suki uses with the note when it recommends the E/M code.
array
required
The clinical note Suki codes from. Each item is one note section with a LOINC code in loinc and the section text in content. Set content.type to TEXT and put the prose in content.text. At least one section must include non-empty text, or generate returns 400.
object
Optional Patient facts that can change new vs established coding and support the visit. Send what you have. Leave the object out when you have nothing useful.
object
Optional Who saw the patient. Include name, NPI, and specialty when your system already stores them.
object
Optional Visit-level details for the encounter you are coding. Use this when you bill by date of service, want time to influence the code, or need to keep your own visit identifiers with the request.
object
Optional Diagnoses already recorded for the encounter. Include them in diagnoses.values, with a code and short description for each diagnosis. Suki uses ICD-10 and IMO diagnoses alongside the clinical note when recommending an E/M code. Your existing diagnoses remain unchanged. Refer to Provide existing diagnoses for which diagnosis types to send.
A successful call returns 201 and a session_id. Store that session_id with the note.
3

Wait Until Coding Finishes

Poll Get E/M coding status with that session_id until status is completed or failed. Status values are created, running, completed, and failed.If webhooks are enabled, you can wait for the E/M Coding notification instead. On that payload, additional_info.session_type is EM_CODES. See E/M Coding webhook events.
4

Retrieve the Codes

When status is completed, call Get E/M codes and show em_codes.values in your review UI. Standalone codes stay available for 30 days. After that, retrieve can return that the codes are no longer available. See Get the generated E/M codes for the response fields.

Example request body

Example responses

Generate (201)

Status (while you poll)

Get codes (when status is completed)

When the coding session reaches completed, call Get E/M codes with the same session_id to retrieve Suki’s recommendations. The response contains the recommended E/M codes in em_codes.values:
Each object in values represents one recommended E/M code. Use the following fields to display the recommendation in your review UI: Each code object includes exactly one set of supporting details: mdm_based_features, time_based_features, or wellness_features. The object present identifies the basis for the recommendation. Use its contents to explain the coding rationale in your review UI.
If em_codes.values is an empty array ([]), Suki did not recommend any E/M codes for the submitted note.
For a complete response example and descriptions of all response fields, refer to Get the generated E/M codes.

Code example

The following code shows the end-to-end logic: submit the finished note, poll status until coding finishes, then retrieve em_codes.values.

Best practices

  • Store the coding session_id with the note. Do not pass an ambient session ID to these endpoints.
  • 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 even though Suki does not use it for that recommendation. Do not send HCC, because that type is not accepted.
  • 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.
  • Match validation and retention errors from E/M Coding error messages by the message text. The API returns sentences, not error ids.

Troubleshooting

Retrieve does not return usable codes for that session. Show the failure, retry generate if appropriate, or fall back to manual coding.
Retrieve returns 404 with a retention message. Call retrieve within 30 days of generate.
Generate returns 400. Send at least one section with loinc, content, and non-empty text.
Status or retrieve returns 404 (invalid em coding session id). Use the session_id from the generate 201 response.

Next steps

E/M Coding API quickstart - Paste-ready Python and TypeScript for the same flow. Get the generated E/M codes - What each field in the code means. Choose Ambient or standalone - Confirm you should submit the note through the standalone APIs.
Last modified on November 5, 2026