Encounter Information

Get encounter information to look up notes, sessions, and artifact availability for an EMR encounter

GET /api/v1/ambient/encounter/{emr_encounter_id}/info

Gets resolved note → session hierarchy for an EMR encounter.

cURL

curl --request GET \
  --url https://sdp.suki.ai/api/v1/ambient/encounter/{emr_encounter_id}/info \
  --header 'sdp_suki_token: <api-key>'

200

{
  "notes": [
    {
      "note_id": "<string>",
      "created_at": "2023-11-07T05:31:56Z",
      "updated_at": "2023-11-07T05:31:56Z",
      "sessions": [
        {
          "session_id": "<string>",
          "status": "<string>",
          "artifacts": [
            "<string>"
          ]
        }
      ]
    }
  ]
}

Use this endpoint to get an overview of all ambient sessions and artifacts associated with an emr_encounter_id.

Pass the same emr_encounter_id you used when creating interoperable ambient sessions. The value can be a UUID or non-UUID string and must be at most 36 characters.

The response provides read-only metadata for the visit, including:

• Note IDs
• Session IDs
• Timestamps
• Session statuses
• Available artifacts

This endpoint does not return note content, transcripts, or recordings. Use the existing session-level and note-level GET endpoints to retrieve those artifacts when they are listed in the response. For example, if artifacts includes content, transcript, or recording, use the corresponding GET endpoint to fetch the data.

Use this endpoint when you need sessions, statuses, and available artifacts for a visit. Use List encounter notes when you only need note IDs for that emr_encounter_id. Refer to Work with shared notes for how to choose between these endpoints in your application UI.

Cross-modality ambient workflows require emr_encounter_id when you create a session. Without it, notes are not interoperable across modalities. Refer to Ambient interoperability for more details.

Code examples

Python

import json
import requests

BASE_URL = "https://sdp.suki.ai"

# Same emr_encounter_id you passed on Create Ambient Session
emr_encounter_id = "<emr_encounter_id>"

# Get sdp_suki_token from Login: POST /api/v1/auth/login
sdp_suki_token = "<sdp_suki_token>"

# Required for single_auth partners
sdp_provider_id = "<sdp_provider_id>"

url = f"{BASE_URL}/api/v1/ambient/encounter/{emr_encounter_id}/info"

headers = {
    "sdp_suki_token": sdp_suki_token,
    "sdp_provider_id": sdp_provider_id,
}

response = requests.get(url, headers=headers, timeout=60)

print("HTTP status:", response.status_code)

try:
    response_body = response.json()
except ValueError:
    print("Response was not JSON:")
    print(response.text)
    raise SystemExit(1)

print("Response body:")
print(json.dumps(response_body, indent=2))

if response.status_code == 200:
    notes = response_body.get("notes") or []
    print(f"Notes found: {len(notes)}")

    for note in notes:
        note_id = note.get("note_id")
        print("note_id:", note_id)
        print("created_at:", note.get("created_at"))
        print("updated_at:", note.get("updated_at"))

        for session in note.get("sessions") or []:
            print("  session_id:", session.get("session_id"))
            print("  status:", session.get("status"))
            print("  artifacts:", session.get("artifacts"))

        print(
            "Use note_id with Get Note Content, Get Note Context, "
            "and Get Note Structured Data."
        )
else:
    print("Get Encounter Info failed.")
    if isinstance(response_body, dict):
        print("code:", response_body.get("code"))
        print("message:", response_body.get("message"))

TypeScript

const BASE_URL = "https://sdp.suki.ai";

// Same emr_encounter_id you passed on Create Ambient Session
const emrEncounterId = "<emr_encounter_id>";

// Get sdp_suki_token from Login: POST /api/v1/auth/login
const sdpSukiToken = "<sdp_suki_token>";

// Required for single_auth partners
const sdpProviderId = "<sdp_provider_id>";

type EncounterInfoSession = {
  session_id?: string;
  status?: string;
  artifacts?: string[];
};

type EncounterInfoNote = {
  note_id?: string;
  created_at?: string;
  updated_at?: string;
  sessions?: EncounterInfoSession[];
};

type GetEncounterInfoResponse = {
  notes?: EncounterInfoNote[];
};

type ApiErrorResponse = {
  code?: number;
  message?: string;
};

const response = await fetch(
  `${BASE_URL}/api/v1/ambient/encounter/${emrEncounterId}/info`,
  {
    method: "GET",
    headers: {
      sdp_suki_token: sdpSukiToken,
      sdp_provider_id: sdpProviderId,
    },
  }
);

const responseText = await response.text();
let responseBody: GetEncounterInfoResponse | ApiErrorResponse | unknown;

try {
  responseBody = responseText ? JSON.parse(responseText) : {};
} catch {
  console.error("Response was not JSON:");
  console.error(responseText);
  throw new Error("Get Encounter Info returned non-JSON response");
}

console.log("HTTP status:", response.status);
console.log("Response body:", JSON.stringify(responseBody, null, 2));

if (response.status === 200) {
  const payload = responseBody as GetEncounterInfoResponse;
  const notes = payload.notes || [];
  console.log(`Notes found: ${notes.length}`);

  for (const note of notes) {
    console.log("note_id:", note.note_id);
    console.log("created_at:", note.created_at);
    console.log("updated_at:", note.updated_at);

    for (const session of note.sessions || []) {
      console.log("  session_id:", session.session_id);
      console.log("  status:", session.status);
      console.log("  artifacts:", session.artifacts);
    }

    console.log(
      "Use note_id with Get Note Content, Get Note Context, and Get Note Structured Data."
    );
  }
} else {
  const error = responseBody as ApiErrorResponse;
  console.error("Get Encounter Info failed.");
  console.error("code:", error.code);
  console.error("message:", error.message);
}

Authorizations

sdp_suki_token · string · header · required

Suki access token (suki_token) from Login or Register. Expires after one hour.

Headers

sdp_provider_id · string

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.

Example:

"provider-123"

Path Parameters

emr_encounter_id · string · required

EMR encounter id (UUID or non-UUID, at most 36 characters). Same value you pass as emr_encounter_id on Ambient session create for interoperable workflows.

Maximum string length: 36

Response

200

application/json

Success Response

Resolved note → session hierarchy for an EMR encounter.

notes · object[]

Notes with sessions and artifact availability for the EMR encounter.

Show child attributes