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