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
Patient Profiles

Patient Profiles

Patient profiles allow you to manage patient information and link multiple sessions to a single patient. This allows Heidi to include patient information in sessions linked to a patient, and use previous sessions as context.

Create a Patient Profile

Method: POST

Path: /patient-profiles

Description: Creates a new patient profile with the provided patient information.

Request

POST /patient-profiles
Authorization: Bearer <your_token>
Content-Type: application/json
 
{
  "first_name": "John",
  "last_name": "Doe",
  "birth_date": "1990-01-15",
  "gender": "MALE",
  "ehr_patient_id": "EHR123456",
  "phone": "+1234567890",
  "email": "john.doe@example.com",
  "demographic_string": "John Doe, M, 1990-01-15",
  "additional_context": "Patient has a history of hypertension"
}

Request Fields:

  • 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, or OTHER
  • ehr_patient_id (string, optional): The patient ID from your system
  • phone (string, optional): Patient's phone number
  • email (string, optional): Patient's email address
  • patient_sex_code (number, optional): Patient sex code
  • identifiers (array, optional): Additional patient identifiers
  • demographic_string (string, optional): Patient display string on the Heidi UI
  • additional_context (string, optional): Additional context about the patient

Response

{
  "data": {
    "id": "5eb7cf5a86d9755df3a6c593",
    "ehr_patient_id": "EHR123456",
    "first_name": "John",
    "last_name": "Doe",
    "birth_date": "1990-01-15",
    "gender": "MALE",
    "phone": "+1234567890",
    "email": "john.doe@example.com",
    "demographic_string": "John Doe, M, 1990-01-15",
    "additional_context": "Patient has a history of hypertension"
  }
}

Update a Patient Profile

Method: PATCH

Path: /patient-profiles/{patient_profile_id}

Description: Updates an existing patient profile with new information. Only the fields provided in the request will be updated.

Request

PATCH /patient-profiles/5eb7cf5a86d9755df3a6c593
Authorization: Bearer <your_token>
Content-Type: application/json
 
{
  "first_name": "John",
  "last_name": "Smith",
  "demographic_string": "John Smith, M, 1990-01-15",
  "phone": "+1987654321",
  "email": "john.smith@example.com"
}

Request Fields:

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

  • 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, or OTHER
  • phone (string, optional): Patient's phone number
  • email (string, optional): Patient's email address
  • identifiers (array, optional): Additional patient identifiers
  • demographic_string (string, optional): Patient display string on the Heidi UI
  • remember_consent (boolean, optional): Whether to remember consent
  • additional_context (string, optional): Additional context about the patient

Response

{
  "data": {
    "id": "5eb7cf5a86d9755df3a6c593",
    "source": "EHR",
    "ehr_patient_id": "EHR123456",
    "first_name": "John",
    "last_name": "Smith",
    "birth_date": "1990-01-15",
    "gender": "MALE",
    "phone": "+1987654321",
    "email": "john.smith@example.com",
    "demographic_string": "John Smith, M, 1990-01-15",
    "additional_context": "Patient has a history of hypertension"
  }
}

Delete Patient Profiles

Method: DELETE

Path: /patient-profiles:batch-delete

Description: Deletes one or more patient profiles. This operation permanently removes the patient profiles and cannot be undone.

Request

DELETE /patient-profiles:batch-delete
Authorization: Bearer <your_token>
Content-Type: application/json
 
{
  "patient_profile_ids": [
    "5eb7cf5a86d9755df3a6c593",
    "5eb7cf5a86d9755df3a6c594"
  ]
}

Request Fields:

  • patient_profile_ids (array, required): Array of patient profile IDs to delete

Response

{
  "is_success": true
}

Link Sessions to a Patient Profile

Method: POST

Path: /patient-profiles/{patient_profile_id}/sessions

Description: Associates one or more sessions with a patient profile. This allows you to group multiple sessions under a single patient, making it easier to track a patient's consultation history.

Request

POST /patient-profiles/5eb7cf5a86d9755df3a6c593/sessions
Authorization: Bearer <your_token>
Content-Type: application/json
 
{
  "session_ids": [
    "1234567890",
    "0987654321"
  ]
}

Request Fields:

  • session_ids (array, required): Array of session IDs to link to the patient profile

Response

{
  "data": [
    {
      "session_id": "1234567890",
      "session_name": "Session 123",
      "created_at": "2024-12-11T03:57:57.921000",
      "updated_at": "2024-12-11T23:41:54.138000"
    },
    {
      "session_id": "0987654321",
      "session_name": "Session 124",
      "created_at": "2024-12-12T10:30:00.000000",
      "updated_at": "2024-12-12T11:15:00.000000"
    }
  ]
}

Get Patient Profiles

Method: GET

Path: /patient-profiles

Description: Retrieves a list of patient profiles. You can optionally filter by EHR patient ID or EHR provider.

Request

GET /patient-profiles
Authorization: Bearer <your_token>

Query Parameters:

  • ehr_patient_id (string, optional): Filter by EHR patient ID
  • ehr_provider (string, optional): Filter by EHR provider name

Response

{
  "data": [
    {
      "id": "5eb7cf5a86d9755df3a6c593",
      "ehr_patient_id": "EHR123456",
      "managed_by": "5eb7cf5a86d9755df3a6c593",
      "first_name": "John",
      "last_name": "Doe",
      "birth_date": "1990-01-15",
      "gender": "MALE",
      "phone": "+1234567890",
      "email": "john.doe@example.com",
      "demographic_string": "",
      "remember_consent": null,
      "additional_context": "Patient has a history of hypertension",
      "session_count": 3
    }
  ]
}

Get Patient Profile by ID

Method: GET

Path: /patient-profiles/{patient_profile_id}

Description: Retrieves detailed information about a specific patient profile by its ID.

Request

GET /patient-profiles/5eb7cf5a86d9755df3a6c593
Authorization: Bearer <your_token>

Response

{
  "data": {
    "id": "5eb7cf5a86d9755df3a6c593",
    "ehr_patient_id": "EHR123456",
    "managed_by": "5eb7cf5a86d9755df3a6c593",
    "first_name": "John",
    "last_name": "Doe",
    "birth_date": "1990-01-15",
    "gender": "MALE",
    "phone": "+1234567890",
    "email": "john.doe@example.com",
    "demographic_string": "",
    "additional_context": "Patient has a history of hypertension"
  }
}

Error Response

If the patient profile is not found:

{
  "detail": {
    "msg": "Patient profile not found",
    "type": "PatientProfileNotFoundError"
  }
}
TemplatesOverview