Sessions

A Heidi session is a collection of notes, documents, and other data that is created by a user. Sessions are the equivalent to a consultation in the clinical workflow.

Create a new session

Method: POST

Path: /sessions

Description: Creates a new session.

Request

POST /sessions
Authorization: Bearer <your_token>
 
Content-Type: application/json
{
  "patient_profile_id": "5eb7cf5a86d9755df3a6c593",
  "ehr_appointment_id": "EHR1234",
}

Request Fields:

• patient_profile_id (string, optional): The ID of the Heidi patient you'd like to create this session for
• ehr_appointment_id (string, optional): The appointment ID you're creating this session for

Response

{
  "session_id": "1234567890"
}

Get Session Details

Method: GET

Path: /sessions/{session_id}

Description: Retrieves detailed information about a specific session.

Request

GET /sessions/1234567890
Authorization: Bearer <your_token>

Response

{
  "session": {
    "session_id": "1234567890",
    "session_name": "Session 123",
    "patient": {
      "name": "",
      "gender": null,
      "dob": null
    },
    "audio": [],
    "clinician_notes": [],
    "consult_note": {
      "status": "CREATED",
      "result": "Consult note content...",
      "heading": "Note",
      "brain": "RIGHT",
      "voice_style": null,
      "generation_method": "TEMPLATE",
      "template_id": null,
      "ai_command_id": null,
      "ai_command_text": null,
      "feedback": null,
      "dictation_cleanup_mode": null
    },
    "duration": 16,
    "created_at": "2024-12-11T03:57:57.921000",
    "updated_at": "2024-12-11T23:41:54.138000",
    "language_code": "en",
    "output_language_code": "en",
    "documents": null,
    "ehr_appt_id": null,
    "ehr_provider": "EHR Provider Name",
    "ehr_patient_id": null
  }
}

Error response

{
  "detail": {
    "msg": "Session not found",
    "type": "SessionNotFoundError"
  }
}

Update Session information

Method: PATCH

Path: /sessions/{session_id}

Description: Updates the details of a session. You can use this endpoint to update the session duration, set the input and output language, patient information, additional context information, and link this session to a patient within your system.

Context

You can provide context for a session by updating the clinician_notes field. This field accepts an array of strings. Context can be used to provide additional information about the session, such as the patient's allergies, medications, or other information that may be relevant to the session.

You can also upload attachments to a session, which will be used as context.

Request

PATCH /sessions/1234567890
Authorization: Bearer <your_token>
Content-Type: application/json
 
{
  "duration": 60,
  "language_code": "en",
  "output_language_code": "en",
  "patient": {
    "name": "John Doe",
    "gender": "MALE",
    "dob": "1990-01-01"
  },
  "clinician_notes": [
    "Note 1",
    "Note 2"
  ],
  "generate_output_without_recording": false
}

Request Fields:

All fields are optional. Only include the fields you want to update:

• duration (number, optional): Session duration in seconds
• language_code (string, optional): Input language code (e.g., "en", "es")
• output_language_code (string, optional): Output language code (e.g., "en", "es")
• transcribe_mode (string, optional): Transcription mode
• patient (object, optional): Patient information object containing:
  • name (string, optional): Patient's name
  • gender (string, optional): Patient's gender. Can be MALE, FEMALE, or OTHER
  • dob (string, optional): Patient's date of birth in ISO format (YYYY-MM-DD)
  • demographic_details (string, optional): Additional demographic information
• clinician_notes (array, optional): Array of strings providing additional context for the session
• ehr_patient_id (string, optional): The patient ID from your EHR system
• ehr_appt_id (string, optional): The appointment ID from your EHR system
• generate_output_without_recording (boolean, optional): Whether to generate output without a recording
• recording_status (string, optional): Recording status
• session_status (string, optional): Session status
• is_consent (boolean, optional): Whether consent has been given
• created_time_local (string, optional): Local creation time
• linked_sessions_for_context (array, optional): Array of session IDs to use as context

Response

{
  "session": {
    "session_id": "1234567890",
    "session_name": "Session 123",
    "patient": {
      "name": "John Doe",
      "gender": "MALE",
      "dob": "1990-01-01"
    },
    "clinician_notes": [],
    "consult_note": {
      "status": "CREATED",
      "result": "Consult note content...",
      "heading": "Note",
      "brain": "RIGHT",
      "voice_style": null,
      "generation_method": "TEMPLATE",
      "template_id": null,
      "ai_command_id": null,
      "ai_command_text": null,
      "feedback": null,
      "dictation_cleanup_mode": null
    },
    "duration": 60,
    "created_at": "2024-12-11T03:57:57.921000",
    "updated_at": "2024-12-11T23:41:54.138000",
    "language_code": "en",
    "output_language_code": "en",
    "documents": null,
    "ehr_appt_id": null,
    "ehr_provider": "EHR Provider Name",
    "ehr_patient_id": null
  }
}

List of sessions

Method: GET

Path: /sessions/linked-user

Description: Retrieve sessions for the linked Heidi user. Note: this is only available after linking a Heidi User +to an API User. Refer to this page for more details.

Request

GET /sessions/linked-user?page_size=10
Authorization: Bearer <your_token>

Response

The response below is truncated, each session returned will include all the details mentioned above in Update Session information.

{
  "sessions": [
    {
      "session_id": "135814281990413956785027749853284386585"
    },
    ...
  ],
  "count": 10,
  "total_count": 13,
  "next_page": null,
  "has_next_page": true
}

Error response

{
  "detail": {
    "msg": "error: no linked user",
    "type": "NoLinkedUserException"
  }
}