> ## 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 Webhook Payload & Response

> Reference for standalone E/M Coding webhook success and failure payloads, including field definitions, error codes, and every _links key

When a standalone E/M Coding session reaches a final processing outcome, Suki sends a success or failure payload to your configured callback URL.

Read the top-level `status` field to identify the payload type:

* `SUCCESS`: Suki finished coding the note.
* `FAILURE`: Coding failed or the session was aborted.

Each payload contains the session identifier. A success payload also contains an `_links` object with links to retrieve the recommended codes and the session status. A failure payload contains an error code and description instead.

> [!NOTE]
>
> * This webhook is only for **standalone** E/M Coding sessions created with [Generate E/M codes](https://developer.suki.ai/em-coding-api-reference/em-coding-sessions/generate.md). E/M codes requested on an ambient visit with `artifacts: ["EM_CODES"]` arrive on the [Ambient webhook](https://developer.suki.ai/documentation/webhook/ambient/overview.md), not this one.
> * For details about when Suki sends these notifications and how to handle each outcome, refer to [E/M Coding webhook overview](https://developer.suki.ai/documentation/webhook/em-coding/overview.md).
> * For request headers, signature verification, and the response your endpoint must return, refer to [Webhook request and response](https://developer.suki.ai/documentation/webhook/payload-and-response.md).

## Success payload

Suki sends a success payload when standalone E/M Coding finishes.

> [!NOTE]
>
> The success payload **always uses this notification shape**.
>
> * Every `_links` key is present.
> * Only `em_codes` and `status` contain links. All other keys are empty arrays on an E/M Coding webhook.
> * What `em_codes` returns depends on the finished note content you submitted to Generate E/M codes, and on any coding context you included with that request, such as visit time or wellness details.
> * Generated codes stay available for **30 days**. Read and store them soon after the webhook arrives.

### Fields

**status** `string` *required*

Always `SUCCESS`.

**session\_id** `string` *required*

Identifier of the E/M Coding session that triggered this notification. This is the session ID returned by [Generate E/M codes](https://developer.suki.ai/em-coding-api-reference/em-coding-sessions/generate.md).

**encounter\_id** `string` *required*

Always an empty string. Standalone E/M Coding sessions are not tied to an encounter. Store your own visit reference next to the `session_id` when you call Generate E/M codes.

**sessions** `array of strings`

Contains only the session identified by `session_id`.

**additional\_info** `object`

Additional context about the notification.

**properties**

**session\_type** `string`

Always `EM_CODES` in an E/M Coding success payload. Use this field to identify the product when multiple Suki products send notifications to the same callback URL.

**practice\_id** `string`

Partner-facing practice identifier. Suki includes this field only when it can resolve the practice associated with the session.

**\_links** `object`

Links to the codes and the session status. Every key is present in the object. Only `em_codes` and `status` contain links. All other keys are empty arrays.

Refer to [The \_links object](#the-_links-object) for the complete list of keys and their descriptions.

### Example success payload

```json theme={"theme":{"light":"one-light","dark":"material-theme-darker"}}
{
  "status": "SUCCESS",
  "session_id": "a953839a-ddcd-407d-b9b0-3ed4b6be4be2",
  "encounter_id": "",
  "sessions": [
    "a953839a-ddcd-407d-b9b0-3ed4b6be4be2"
  ],
  "additional_info": {
    "session_type": "EM_CODES",
    "practice_id": "your-practice-id"
  },
  "_links": {
    "em_codes": [
      {
        "href": "/em-codes/a953839a-ddcd-407d-b9b0-3ed4b6be4be2",
        "method": "GET",
        "name": "a953839a-ddcd-407d-b9b0-3ed4b6be4be2",
        "type": "application/json"
      }
    ],
    "status": [
      {
        "href": "/em-codes/a953839a-ddcd-407d-b9b0-3ed4b6be4be2/status",
        "method": "GET",
        "name": "a953839a-ddcd-407d-b9b0-3ed4b6be4be2",
        "type": "application/json"
      }
    ],
    "contents": [],
    "transcripts": [],
    "structured_data": [],
    "section_structured_data": [],
    "diagnoses": [],
    "orders": [],
    "encounter_content": [],
    "encounter_structured_data": [],
    "encounter_section_structured_data": [],
    "encounter_em_codes": [],
    "encounter_diagnoses": [],
    "encounter_orders": []
  }
}
```

## The \_links object

The `_links` object contains the API paths your application can call to retrieve standalone E/M Coding results.

Each key contains an array of link objects. Every link object has the same four fields:

| Field | Description |
| :- | :- |
| `href` | Resource path relative to `/api/v1`. Refer to [Build the full URL](https://developer.suki.ai/documentation/webhook/em-coding/retrieve-results.md#build-the-full-url) for how to construct the complete request URL. |
| `method` | HTTP method for the request. Always `GET`. |
| `name` | E/M Coding session ID associated with the resource. |
| `type` | Response media type. Always `application/json`. |

The two keys that contain links each hold exactly **one link**:

| Key | `href` pattern | Description |
| :- | :- | :- |
| `em_codes` | `/em-codes/{session_id}` | Recommended Evaluation and Management codes for the session. |
| `status` | `/em-codes/{session_id}/status` | Current status of the E/M Coding session. |

All other keys are empty arrays on an E/M Coding webhook.

> [!TIP]
>
> Make your webhook parser ignore unrecognized keys in `_links`. This allows your integration to handle new link types added in future releases without breaking the webhook handler.

## Failure payload

Suki sends a failure payload when standalone E/M Coding fails or when a session is aborted.

Unlike the success payload, the failure payload does not contain `sessions`, `_links`, or `additional_info`. Instead, it includes an error code and a description of the error.

### Fields

**status** `string` *required*

Always `FAILURE`.

**session\_id** `string` *required*

Identifier of the E/M Coding session that failed or was aborted.

**encounter\_id** `string` *required*

Present on every failure payload, but not meaningful for standalone E/M Coding. Do not use it to look up the visit.

**error\_code** `string` *required*

Machine-readable code that identifies the reported error. Refer to [Error codes](#error-codes).

**error\_detail** `string` *required*

Human-readable description of the error. This field can contain an empty string when Suki has no additional details.

### Example failure payload

```json theme={"theme":{"light":"one-light","dark":"material-theme-darker"}}
{
  "status": "FAILURE",
  "session_id": "20965414-929a-4f71-a3e5-b92bec07d086",
  "encounter_id": "",
  "error_code": "ERROR_CODE_UNSPECIFIED",
  "error_detail": "Error during E/M code generation"
}
```

> [!WARNING]
>
> A failure payload does not contain `additional_info`, so it does not identify the product through `session_type`.
>
> If multiple Suki products send notifications to the same callback URL, match `session_id` against the E/M Coding session IDs your application saved from Generate E/M codes.

### Error codes

The `error_code` field identifies the type of error reported in the failure notification.

| `error_code` | Description |
| :- | :- |
| `ERROR_CODE_UNSPECIFIED` | Coding failed or the session was aborted. Check `error_detail` for the reported reason. |
| `ERROR_CODE_NOTIFICATION_GENERATION_FAILURE` | Suki could not prepare the webhook body for the session. In this case, `error_detail` is `Error Preparing Webhook Notification`. Call [Get E/M Coding status](https://developer.suki.ai/em-coding-api-reference/em-coding-sessions/status.md) to determine the actual session outcome. |

Use `error_code` to identify and handle error conditions in your application. Log `error_detail` to help with troubleshooting or to provide context when notifying coding staff.

> [!TIP]
>
> `error_detail` helps you understand what went wrong in logs or when you notify your team or clinician, but Suki can revise that wording at any time. If your handler needs to choose a path, such as retry versus alert, match on `error_code` instead of comparing the detail string.

## Next steps

 **[Retrieve E/M Coding results](https://developer.suki.ai/documentation/webhook/em-coding/retrieve-results.md)** - Read the codes and session status.

 **[E/M Coding webhook overview](https://developer.suki.ai/documentation/webhook/em-coding/overview.md)** - When Suki sends E/M Coding webhooks and how to handle each outcome.

 **[Webhook event catalog](https://developer.suki.ai/documentation/webhook/event-catalog.md)** - Payload references for other Suki products.

 **[E/M Coding asynchronous notifications](https://developer.suki.ai/em-coding-api-reference/asynchronous/webhook.md)** - OpenAPI specification and sample handlers.


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