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.

• This webhook is only for standalone E/M Coding sessions created with Generate E/M codes. E/M codes requested on an ambient visit with artifacts: ["EM_CODES"] arrive on the Ambient webhook, not this one.
• For details about when Suki sends these notifications and how to handle each outcome, refer to E/M Coding webhook overview.
• For request headers, signature verification, and the response your endpoint must return, refer to Webhook request and response.

​

Success payload

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

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.

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.

Show 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 for the complete list of keys and their descriptions.

​

Example success payload

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

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

{
  "status": "FAILURE",
  "session_id": "20965414-929a-4f71-a3e5-b92bec07d086",
  "encounter_id": "",
  "error_code": "ERROR_CODE_UNSPECIFIED",
  "error_detail": "Error during E/M code generation"
}

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

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 - Read the codes and session status.

E/M Coding webhook overview - When Suki sends E/M Coding webhooks and how to handle each outcome.

Webhook event catalog - Payload references for other Suki products.

E/M Coding asynchronous notifications - OpenAPI specification and sample handlers.