Get the Generated E/M Codes

Read the recommended E/M code and the reason after coding finishes, from a standalone coding session or from an ambient note

Retrieve the recommended E/M codes and their supporting rationale after Suki completes coding for an ambient session or a standalone note. Use this when you requested E/M codes as part of an ambient visit, or when you generated them separately using the standalone E/M Coding APIs.

Both workflows return the same code structure. The difference is how you identify the coding result and how long it remains available.

​

From a note you sent yourself

Use this path after Generate E/M codes from a note.

1. Confirm Get E/M coding status is completed, or handle a success E/M Coding webhook.
2. Call Get E/M codes with the coding session_id from generate. Do not pass an ambient session ID here.

​

Path parameters

session_id · string · required

The E/M coding session ID returned by generate (201). Not an ambient session ID.

​

Example request

GET /api/v1/em-codes/{session_id}

The E/M codes generated using the standalone E/M Coding APIs stay available for 30 days. After that, retrieve returns 404 with em codes for session older than 30 days is not available.

​

From an ambient visit

Use this path after Add E/M codes to an ambient visit.

The E/M codes generated as part of an ambient session are stored with the note. Read them after ambient status is completed. Confirm Session status before you treat the note or the codes as ready. An ambient webhook SUCCESS means processing finished; still confirm status.

​

With the rest of the note

If you already load structured data, em_codes can sit next to diagnoses, orders, and section values under structured_data.em_codes:

• Session structured data
• Encounter structured data
• Note structured data

​

When you only need the codes

Scope	Endpoint	Path parameter	What you get
This recording	GET /api/v1/ambient/session/{ambient_session_id}/structured-data/em-codes	ambient_session_id from create	Codes for that ambient session.
The note	GET /api/v1/ambient/note/{note_id}/structured-data/em-codes	note_id from create	Codes stored on the note.
The encounter	GET /api/v1/ambient/encounter/{encounter_id}/structured-data/em-codes	encounter_id for the visit	Codes from the latest completed session for that encounter, the same session other encounter structured data uses.

The ambient success webhook always includes _links.em_codes and _links.encounter_em_codes, so you can call those URLs without building the path yourself. Those links return empty values unless the session was created with artifacts: ["EM_CODES"].

​

Example em_codes response

Dedicated E/M retrieve endpoints return recommended codes under em_codes.values. Ambient codes-only endpoints return the same em_codes object. Combined structured-data responses place that object under structured_data.em_codes.

The example below includes MDM detail objects. Those detail fields appear when the API returns them. They are not required on every code.

{
  "em_codes": {
    "values": [
      {
        "id": "01JQ8Z2W9X4Y6Z8A0B2C4D6E8F",
        "code": "99214",
        "family": "PROBLEM_BASED",
        "level": 4,
        "patient_type": "ESTABLISHED_PATIENT",
        "modifiers": ["25"],
        "add_on_codes": [],
        "mdm_based_features": {
          "problem_complexity": "PROBLEM_COMPLEXITY_MODERATE",
          "data_reviewed": "DATA_REVIEWED_LIMITED",
          "risk": "RISK_MODERATE",
          "rationale": "Moderate complexity with prescription drug management",
          "problem_complexity_details": {
            "level": "PROBLEM_COMPLEXITY_MODERATE",
            "evidence": "Two stable chronic illnesses managed",
            "entities": [
              {
                "entity": "Essential hypertension",
                "evidence": "BP 150/95 discussed, lisinopril continued"
              }
            ]
          },
          "data_reviewed_details": {
            "level": "DATA_REVIEWED_LIMITED",
            "evidence": "Prior labs reviewed",
            "entities": [
              {
                "entity": "Basic metabolic panel",
                "evidence": "Labs from 2026-01-01 reviewed and interpreted"
              }
            ]
          },
          "risk_details": {
            "level": "RISK_MODERATE",
            "evidence": "Prescription drug management",
            "entities": [
              {
                "entity": "Prescription drug management",
                "evidence": "Lisinopril dose increased to 20mg"
              }
            ]
          }
        }
      }
    ]
  }
}

​

Response fields

Each object in em_codes.values is one recommended E/M code. Use these fields to display the recommendation in your application’s UI for the clinician reviewing the note.

Exactly one of mdm_based_features, time_based_features, or wellness_features is populated on each code. Use that object to explain the coding rationale.

id · string

E/M code record ID.

code · string

The recommended E/M code, such as 99214.

family · string

The E/M code family. Allowed values: PROBLEM_BASED, WELLNESS_PREVENTIVE, ADD_ON_CODE, CONSULTATIONS, PREVENTIVE_MEDICINE_SERVICES, PROLONGED_SERVICES, and TRANSITIONAL_CARE_MANAGEMENT_SERVICES.

level · number

The recommended coding level.

patient_type · string

The patient category used for the recommendation (NEW_PATIENT or ESTABLISHED_PATIENT).

modifiers · array

Code modifiers for the recommendation, such as 25. Show this only when the list has values.

add_on_codes · array

Additional codes recommended with the E/M code. Show this only when the list has values.

mdm_based_features · object

Optional Medical decision making (MDM) details when Suki coded on MDM. Present only when this is the basis for the recommendation.

Show properties

rationale · string

Supporting sentence for the recommendation.

problem_complexity · string

Problem complexity value.

data_reviewed · string

Data reviewed value.

risk · string

Risk value.

problem_complexity_details · object

Optional Problem complexity assessment when returned.

Show properties

level · string

Problem complexity level for this assessment.

evidence · string

Supporting text for the problem complexity assessment.

entities · array

Supporting problems. Each item includes entity and evidence.

data_reviewed_details · object

Optional Data-reviewed assessment when returned.

Show properties

level · string

Data reviewed level for this assessment.

evidence · string

Supporting text for the data-reviewed assessment.

entities · array

Supporting data items. Each item includes entity and evidence.

risk_details · object

Optional Risk assessment when returned.

Show properties

level · string

Risk level for this assessment.

evidence · string

Supporting text for the risk assessment.

entities · array

Supporting risk factors. Each item includes entity and evidence.

time_based_features · object

Optional Time-based coding details when Suki coded on time. Present only when this is the basis for the recommendation.

Show properties

time_taken · number

Visit time in minutes.

evidence · string

Supporting text for the time-based recommendation.

wellness_features · object

Optional Wellness or preventive coding details when Suki coded on wellness. Present only when this is the basis for the recommendation.

Show properties

evidence · string

Supporting text for the wellness or preventive recommendation.

​

What to show the reviewer

Show the recommended code as a suggestion for the reviewer to check, not as a final billing decision. The reviewer is usually the clinician who completed the note, but your application may also send the recommendation to a coding team. In either case, require the reviewer to accept or change the code before sending it to billing.

Display the recommended code (for example, 99214) prominently, along with whether the patient is new or established and the recommended level. Then show the supporting information from the code’s feature object:

• Medical decision making: Show rationale. When medical decision making details are available, also show the problems, data reviewed, and risk, along with the evidence for each.
• Time-based coding: Show the total minutes and the supporting evidence.
• Wellness coding: Show the supporting evidence.

This gives the reviewer the information behind the recommendation without requiring them to read the entire note again. Show modifiers and add-on codes only when the corresponding lists contain values.

If em_codes.values is empty, display a message that no code was recommended. Keep the note available for review. An empty list does not indicate a failed request. For ambient visits, the note can be complete even when Suki has no coding recommendation.

Let the reviewer accept the recommended code or select a different one. Once they confirm their choice, your application can pass the accepted code to its existing billing or EHR workflow. Suki does not submit claims, send codes to payers, or update the EHR.

​

Best practices

• Wait until status is completed before you retrieve. On standalone, poll until completed (do not retrieve on failed). On ambient, wait until ambient status is completed.
• Present code, patient_type, level, and the supporting reason from the single populated feature set. Omit empty modifiers and add_on_codes.
• Retrieve standalone codes within 30 days. After that, retrieve returns 404 with em codes for session older than 30 days is not available.
• Prefer the codes-only endpoints when you only need the E/M code. Use combined structured-data endpoints when you already load diagnoses and orders together.
• For ambient retention 404 responses, see troubleshooting in Add E/M codes to an ambient visit. Do not assume the standalone 30-day window applies there.

​

Troubleshooting

Empty em_codes.values

Dedicated E/M endpoints still return an em_codes object with values: []. Treat that as no recommendation, not as a failed HTTP call.

Standalone Status Is Failed

Do not expect codes on retrieve for that session. Retry generate or fall back to manual coding.

Ambient Coding Failed or Was Skipped

Ambient can still complete successfully. Show the note. Empty values means no code for this visit.

Encounter EM Retrieve Before Session Completes

Can return 200 with empty values. Poll or wait until ambient status is completed.

Standalone Codes Older Than 30 Days

Standalone retrieve returns 404 with em codes for session older than 30 days is not available. Retrieve sooner, or generate again if you still have the note.

​

Next steps

What E/M Coding is - What the E/M code means before you map fields.

Get E/M codes - Standalone retrieve API reference.

Retrieve Ambient results - Use ambient webhook _links for session and encounter E/M codes.

Retrieve E/M Coding results - Use the standalone E/M webhook em_codes link after coding finishes.