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

# Retrieve E/M Codes Using Ambient Session ID

> Retrieve E/M codes generated for an ambient session that opted into EM_CODES

Use this endpoint to retrieve Evaluation and Management (E/M) codes for an ambient session. Pass the `ambient_session_id` to get the `em_codes` generated for that session.

The session must opt in with `artifacts: ["EM_CODES"]` on [Create ambient session](https://developer.suki.ai/api-reference/ambient-sessions/create.md).

> [!NOTE]
>
> Wait until the ambient session is `completed` before you call this endpoint.

## Code examples

**Language tabs (agents):** Equivalent code samples are available in: Python, TypeScript. Humans see one language at a time. Use the variant that matches the user's stack; behavior is the same across tabs.

> [tab] Python
>
> ```python theme={"theme":{"light":"one-light","dark":"material-theme-darker"}}
> import requests
>
> ambient_session_id = "123dfg-456dfg-789dfg-012dfg"
> url = f"https://sdp.suki.ai/api/v1/ambient/session/{ambient_session_id}/structured-data/em-codes"
>
> headers = {
>     "sdp_suki_token": "<sdp_suki_token>",
>     "sdp_provider_id": "<sdp_provider_id>",
> }
>
> response = requests.get(url, headers=headers)
> print(response.status_code)
> print(response.json())
> ```

> [tab] TypeScript
>
> ```typescript theme={"theme":{"light":"one-light","dark":"material-theme-darker"}}
> const ambientSessionId = "123dfg-456dfg-789dfg-012dfg";
> const url = `https://sdp.suki.ai/api/v1/ambient/session/${ambientSessionId}/structured-data/em-codes`;
>
> const response = await fetch(url, {
>   headers: {
>     sdp_suki_token: "<sdp_suki_token>",
>     sdp_provider_id: "<sdp_provider_id>",
>   },
> });
> console.log(response.status, await response.json());
> ```


## OpenAPI

````yaml GET /api/v1/ambient/session/{ambient_session_id}/structured-data/em-codes
openapi: 3.0.1
info:
  title: Suki Developer Platform
  description: >-
    REST and WebSocket APIs for the Suki Developer Platform. Authenticate with
    Login or Register to obtain a Suki access token, then integrate ambient
    clinical documentation, form filling, transcription, content rewrite, and
    reference metadata endpoints.
  contact: {}
  version: '1.0'
servers:
  - url: https://sdp.suki.ai
    description: >-
      Production base URL for Suki Developer Platform REST APIs. WebSocket
      endpoints use the same host with `wss://`.
security:
  - SukiTokenAuth: []
paths:
  /api/v1/ambient/session/{ambient_session_id}/structured-data/em-codes:
    get:
      tags:
        - /api/v1/ambient/session
      summary: Gets the E/M codes for the ambient session.
      description: >-
        Gets the E/M codes generated for an ambient session that opted into
        EM_CODES on create.
      parameters:
        - name: ambient_session_id
          in: path
          description: >-
            UUID for the ambient session. Use the `ambient_session_id` returned
            from Create Ambient Session, or the UUID you supplied in that
            request.
          required: true
          schema:
            type: string
        - $ref: '#/components/parameters/ProviderIdHeader'
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/controllers.SessionEMCodesStructuredDataResponse
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/controllers.BadRequestError'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/controllers.AuthenticationError'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/controllers.NotFoundError'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/controllers.InternalServerError'
      security:
        - SukiTokenAuth: []
components:
  parameters:
    ProviderIdHeader:
      name: sdp_provider_id
      in: header
      description: >-
        **Optional** for standard partners.


        **Required** for:


        - **Bearer authentication.** Use the same `provider_id` returned by the
        Login or Register API.

        - **Single Auth Token authentication.** Include the same `provider_id`
        on every request as `sdp_provider_id`.
      required: false
      schema:
        type: string
        example: provider-123
  schemas:
    controllers.SessionEMCodesStructuredDataResponse:
      description: >-
        Response body for the
        /session/{ambient_session_id}/structured-data/em-codes endpoint
      type: object
      properties:
        em_codes:
          $ref: '#/components/schemas/controllers.EMCodingResult'
    controllers.BadRequestError:
      description: Bad Request Response
      type: object
      properties:
        code:
          type: integer
          example: 400
        message:
          type: string
          example: invalid request
    controllers.AuthenticationError:
      description: Authentication Failure Response
      type: object
      properties:
        code:
          type: integer
          example: 401
        message:
          type: string
          example: invalid token
    controllers.NotFoundError:
      description: Not Found Response
      type: object
      properties:
        code:
          type: integer
          example: 404
        message:
          type: string
          example: not found
    controllers.InternalServerError:
      description: Internal Server Error Response
      type: object
      properties:
        code:
          type: integer
          example: 500
        message:
          type: string
          example: internal server error
    controllers.EMCodingResult:
      description: Generated E/M codes
      type: object
      properties:
        values:
          type: array
          items:
            $ref: '#/components/schemas/controllers.EMCodeResponse'
    controllers.EMCodeResponse:
      description: A single generated E/M code. Exactly one feature set is populated.
      type: object
      properties:
        add_on_codes:
          type: array
          items:
            type: string
          example: []
        code:
          type: string
          example: '99214'
        family:
          type: string
          enum:
            - PROBLEM_BASED
            - WELLNESS_PREVENTIVE
            - ADD_ON_CODE
            - CONSULTATIONS
            - PREVENTIVE_MEDICINE_SERVICES
            - PROLONGED_SERVICES
            - TRANSITIONAL_CARE_MANAGEMENT_SERVICES
          example: PROBLEM_BASED
        id:
          description: E/M code record ID.
          type: string
          example: 01JQ8Z2W9X4Y6Z8A0B2C4D6E8F
        level:
          description: Level of service.
          type: integer
          example: 4
        mdm_based_features:
          $ref: '#/components/schemas/controllers.EMMDMBasedFeatures'
        modifiers:
          type: array
          items:
            type: string
          example:
            - '25'
        patient_type:
          type: string
          enum:
            - NEW_PATIENT
            - ESTABLISHED_PATIENT
          example: ESTABLISHED_PATIENT
        time_based_features:
          $ref: '#/components/schemas/controllers.EMTimeBasedFeatures'
        wellness_features:
          $ref: '#/components/schemas/controllers.EMWellnessFeatures'
    controllers.EMMDMBasedFeatures:
      description: Features behind a medical-decision-making (MDM) based E/M code
      type: object
      properties:
        data_reviewed:
          type: string
          example: DATA_REVIEWED_LIMITED
        data_reviewed_details:
          $ref: '#/components/schemas/controllers.EMDataReviewedDetails'
        problem_complexity:
          type: string
          example: PROBLEM_COMPLEXITY_MODERATE
        problem_complexity_details:
          $ref: '#/components/schemas/controllers.EMProblemComplexityDetails'
        rationale:
          type: string
          example: Moderate complexity with prescription drug management
        risk:
          type: string
          example: RISK_MODERATE
        risk_details:
          $ref: '#/components/schemas/controllers.EMRiskDetails'
    controllers.EMTimeBasedFeatures:
      description: Features behind a time-based E/M code
      type: object
      properties:
        evidence:
          type: string
          example: 35 minutes of total clinician time documented
        time_taken:
          description: Visit time in minutes.
          type: integer
          example: 35
    controllers.EMWellnessFeatures:
      description: Features behind a wellness / preventive E/M code
      type: object
      properties:
        evidence:
          type: string
          example: Annual wellness visit with preventive counseling
    controllers.EMDataReviewedDetails:
      description: Data-reviewed assessment behind an MDM-based code
      type: object
      properties:
        entities:
          type: array
          items:
            $ref: '#/components/schemas/controllers.EMDataEntity'
        evidence:
          type: string
          example: Prior labs reviewed
        level:
          description: DataReviewed name.
          type: string
          example: DATA_REVIEWED_LIMITED
    controllers.EMProblemComplexityDetails:
      description: Problem complexity assessment behind an MDM-based code
      type: object
      properties:
        entities:
          type: array
          items:
            $ref: '#/components/schemas/controllers.EMProblemEntity'
        evidence:
          type: string
          example: Two stable chronic illnesses managed
        level:
          description: ProblemComplexity name.
          type: string
          example: PROBLEM_COMPLEXITY_MODERATE
    controllers.EMRiskDetails:
      description: Risk assessment behind an MDM-based code
      type: object
      properties:
        entities:
          type: array
          items:
            $ref: '#/components/schemas/controllers.EMRiskEntity'
        evidence:
          type: string
          example: Prescription drug management
        level:
          description: Risk name.
          type: string
          example: RISK_MODERATE
    controllers.EMDataEntity:
      description: A reviewed data element, with its supporting evidence
      type: object
      properties:
        entity:
          type: string
          example: Basic metabolic panel
        evidence:
          type: string
          example: Labs from 2026-01-01 reviewed and interpreted
    controllers.EMProblemEntity:
      description: A problem the coder identified, with its supporting evidence
      type: object
      properties:
        entity:
          type: string
          example: Essential hypertension
        evidence:
          type: string
          example: BP 150/95 discussed, lisinopril continued
    controllers.EMRiskEntity:
      description: A risk factor the coder identified, with its supporting evidence
      type: object
      properties:
        entity:
          type: string
          example: Prescription drug management
        evidence:
          type: string
          example: Lisinopril dose increased to 20mg
  securitySchemes:
    SukiTokenAuth:
      type: apiKey
      in: header
      name: sdp_suki_token
      description: >-
        Suki access token (`suki_token`) from Login or Register. Expires after
        one hour.

````

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