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

# 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

Quick summary

After coding finishes, read `em_codes.values`. Each item is one recommended E/M code. Exactly one of `mdm_based_features`, `time_based_features`, or `wellness_features` is populated on that item.

Last updated:
November 2026

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](https://developer.suki.ai/documentation/how-to/em-coding/generate-standalone.md).

1. Confirm [Get E/M coding status](https://developer.suki.ai/em-coding-api-reference/em-coding-sessions/status.md) is `completed`, or handle a success [E/M Coding webhook](https://developer.suki.ai/em-coding-api-reference/asynchronous/webhook.md).
2. Call [Get E/M codes](https://developer.suki.ai/em-coding-api-reference/em-coding-sessions/get.md) 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

```bash theme={"theme":{"light":"one-light","dark":"material-theme-darker"}}
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](https://developer.suki.ai/documentation/how-to/em-coding/generate-with-ambient.md).

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](https://developer.suki.ai/api-reference/ambient-content/status.md) 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](https://developer.suki.ai/api-reference/ambient-content/structured-data.md)
* [Encounter structured data](https://developer.suki.ai/api-reference/ambient-content/encounter-structured-data.md)
* [Note structured data](https://developer.suki.ai/api-reference/ambient-content/note-structured-data.md)

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

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

```json expandable theme={"theme":{"light":"one-light","dark":"material-theme-darker"}}
{
  "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.

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

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

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

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

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

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

> [!TIP]
>
> * 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](https://developer.suki.ai/documentation/how-to/em-coding/generate-with-ambient.md). Do not assume the standalone 30-day window applies there.

## Troubleshooting

> [accordion] 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.

> [accordion] Standalone Status Is Failed
>
> Do not expect codes on retrieve for that session. Retry generate or fall back to manual coding.

> [accordion] Ambient Coding Failed or Was Skipped
>
> Ambient can still complete successfully. Show the note. Empty `values` means no code for this visit.

> [accordion] Encounter EM Retrieve Before Session Completes
>
> Can return `200` with empty `values`. Poll or wait until ambient status is `completed`.

> [accordion] 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](https://developer.suki.ai/documentation/concepts/em-coding/what-is-em-coding.md)** - What the E/M code means before you map fields.

 **[Get E/M codes](https://developer.suki.ai/em-coding-api-reference/em-coding-sessions/get.md)** - Standalone retrieve API reference.

 **[Retrieve Ambient results](https://developer.suki.ai/documentation/webhook/ambient/retrieve-results.md)** - Use ambient webhook `_links` for session and encounter E/M codes.

 **[Retrieve E/M Coding results](https://developer.suki.ai/documentation/webhook/em-coding/retrieve-results.md)** - Use the standalone E/M webhook `em_codes` link after coding finishes.


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