Unfortunately, the Heidi API and Widget are no longer available for future integrations in Australia and New Zealand. If you are a current Heidi customer looking to integrate, reach out to your Customer Success representative. Otherwise, contact our team to find out what this means for you.
Heidi API
Sessions
Overview

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_appt_id": "EHR1234",
  "ehr_patient_id": "PAT-001",
  "timezone": "Australia/Sydney",
  "language_code": "en",
  "output_language_code": "en"
}

Request Fields:

All fields are optional. Unknown fields are ignored — use the names below, not aliases.

  • patient_profile_id (string, optional): The ID of the Heidi patient this session belongs to. Must be owned by the linked user.
  • ehr_appt_id (string, optional): The appointment ID from your EHR. Maximum 256 characters.
  • ehr_patient_id (string, optional): The patient ID from your EHR. Maximum 256 characters.
  • timezone (string, optional): IANA timezone for the session (for example Australia/Sydney). Required when created_time_local includes a UTC offset.
  • language_code (string, optional): Input language code (for example en).
  • language_code_list (array, optional): Additional input language codes.
  • output_language_code (string, optional): Output language code for generated notes.
  • template_id (string, optional): Consult-note template for this session only. Pass "AUTO_MODE" for automatic template selection. An unknown or inaccessible id returns 4xx.
  • created_time_local (string, optional): Local appointment time. Must be within 10 years past and 2 years future.

Response

{
  "session_id": "1234567890"
}

Create or resume a session for an EHR patient

Method: POST

Path: /workflows/session

Description: Sets up a patient and a session in a single request. Heidi finds the patient by ehr_patient_id, creating a patient profile if one doesn't exist or updating its details if it does. It then creates a new session linked to that patient, or returns an existing session if you pass its session_id.

Use this endpoint instead of creating a patient profile, creating a session and linking them in separate calls. Use Create a new session instead if you already have a Heidi patient_profile_id, or Create a Patient Profile if the patient has no EHR ID.

This endpoint requires a linked account.

Request

POST /workflows/session
Authorization: Bearer <your_token>
Content-Type: application/json
 
{
  "patient": {
    "ehr_patient_id": "PAT-001",
    "first_name": "Jane",
    "last_name": "Doe",
    "birth_date": "1985-04-12",
    "gender": "female"
  },
  "session": {
    "ehr_appt_id": "APPT-789",
    "timezone": "Australia/Sydney",
    "language_code": "en",
    "output_language_code": "en"
  }
}

Request Fields:

Unknown fields are rejected with 422 Unprocessable Entity at every level of the request.

patient (object, required): The patient this session is for.

  • ehr_patient_id (string, required): The patient ID from your EHR, between 1 and 256 characters. Heidi uses it to find an existing patient profile.
  • first_name (string, optional): Patient's first name.
  • last_name (string, optional): Patient's last name.
  • birth_date (string, optional): Patient's date of birth in ISO format (YYYY-MM-DD).
  • gender (string, optional): Patient's gender. Can be male, female, other, or unknown.
  • email (string, optional): Patient's email address.
  • phone (string, optional): Patient's phone number in international format, including the country code (for example +61412345678).
  • patient_sex_code (number, optional): Patient sex code.
  • demographic_string (string, optional): Patient display string on the Heidi UI.
  • additional_context (string, optional): Additional context about the patient.

Empty or whitespace-only strings are treated as if the field was omitted.

session (object, optional): Settings for a new session. Omit it, or send {}, to create a session with default settings.

  • session_id (string, optional): A session_id returned by a previous call. Pass it to resume that session instead of creating a new one. See Resuming a session.
  • ehr_appt_id (string, optional): The appointment ID from your EHR. Maximum 256 characters.
  • timezone (string, optional): IANA timezone for the session (for example Australia/Sydney). Must be a recognised timezone, otherwise the request is rejected with 422. Required when created_time_local includes a UTC offset.
  • created_time_local (string, optional): Local appointment time. Must be within 10 years past and 2 years future.
  • language_code (string, optional): Input language code (for example en).
  • language_code_list (array, optional): Additional input language codes.
  • output_language_code (string, optional): Output language code for generated notes.
  • template_id (string, optional): Consult-note template for this session only. Pass "AUTO_MODE" for automatic template selection. An unknown or inaccessible id returns 4xx.

New sessions are tagged with the patient's ehr_patient_id, so you don't need to send it again.

Patient matching

  • New patient: If no patient profile has this ehr_patient_id, one is created from the request and patient_created is true.
  • Returning patient: If a profile already exists, its first name, last name, date of birth, gender, email and demographic string are updated to match the request. An omitted, null or empty value never clears a stored value. patient_created is false.
  • Fields set only on creation: phone, patient_sex_code and additional_context are not updated on an existing profile. Use Update a Patient Profile to change them.

Resuming a session

Pass session.session_id to resume a session from a previous call, for example when the clinician reopens the same appointment. The other session fields are only used if a new session has to be created.

  • Session found: The existing session is returned unchanged and session_created is false. Its template, timezone and other settings are not modified.
  • Session deleted: If you deleted the session, a new one is created and session_created is true.
  • Session not found: If the session_id doesn't exist or belongs to another user, the request is rejected with 400 ErrSessionNotFound before any changes are made.
  • Different patient: If the session is linked to a different patient than ehr_patient_id, the request is rejected with 400 ErrSessionPatientMismatch. The patient profile has already been created or updated at this point, but no session is returned.

Sessions that aren't linked to any patient can be resumed with any ehr_patient_id.

Response

{
  "session_id": "1234567890",
  "patient_profile_id": "5eb7cf5a86d9755df3a6c593",
  "patient_created": false,
  "session_created": true
}

Response Fields:

  • session_id (string): The ID of the new or resumed session.
  • patient_profile_id (string|null): The ID of the patient profile linked to the session. null when a resumed session isn't linked to a patient.
  • patient_created (boolean): true when a new patient profile was created, false when an existing one was found.
  • session_created (boolean): true when a new session was created, false when an existing session was resumed.

Error responses

Returned with 400 Bad Request when session.session_id doesn't exist or belongs to another user:

{
  "detail": {
    "type": "ErrSessionNotFound",
    "msg": "Session not found: session_id: 1234567890"
  }
}

Returned with 400 Bad Request when session.session_id is linked to a different patient:

{
  "detail": {
    "type": "ErrSessionPatientMismatch",
    "msg": "Session is linked to a different patient: session_id: 1234567890, ehr_patient_id: PAT-001"
  }
}

Returned with 404 Not Found when the endpoint isn't available:

{
  "detail": {
    "type": "ErrOpenApiSessionWorkflowDisabled",
    "msg": "Open API session workflow is not enabled"
  }
}

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"
  }
}

Delete a session

Method: DELETE

Path: /sessions/{session_id}

Description: Deletes a session.

Request

DELETE /sessions/1234567890
Authorization: Bearer <your_token>

Response

{
  "is_success": true
}

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
  }
}
Patient ProfilesContext