Patient Data Structure

JSON format to configure SofIA chat with the patient’s clinical history and complete context

The patientdata property allows you to provide the patient’s clinical history and context to SofIA. While optional, it is strongly recommended — it enables SofIA to reference the patient’s background when generating reports and answering clinical questions.

Data Structure

The patientdata prop accepts a JSON object with the following structure:

Field	Type	Description
fullName	string	Patient’s full name
birthDate	string	Date of birth (any format: YYYY-MM-DD, DD/MM/YYYY, etc.)
phone	string	Contact phone number
address	string	Patient’s address
extraData	object	Flexible key-value object for any additional clinical data
signedConsent	{ signed: boolean, date?: string } or undefined	Item to indicate if the patient has signed the consent form to be recorded. Optional. This requires that the showconsentindicator property be true in order to be enabled.

The fields fullName, birthDate, phone, and address are automatically anonymized in AI processing. SofIA replaces these values with placeholders before sending data to the AI engine, then restores them in the final output. This ensures HIPAA/GDPR compliance.

All patient data shown in the examples below is entirely fictional. Never use real patient information in configuration examples, testing environments, or source code.

Usage Examples

Minimal Example

The simplest usage with just the patient’s identity:

{
  "fullName": "Jane Doe",
  "birthDate": "1985-05-15"
}

Standard Example

A typical usage including contact information and medical history:

{
  "fullName": "Jane Doe",
  "birthDate": "1985-05-15",
  "phone": "6425482447",
  "address": "123 Main Street, City",
  "extraData": {
    "medical_practice": "Cardiology",
    "patient_medical_notes": {
      "notes": [
        {
          "consultation": "Cardiology follow-up",
          "date": "2024-10-25",
          "summary": "Stable blood pressure with current medication. ECG normal."
        },
        {
          "consultation": "General checkup",
          "date": "2024-08-12",
          "summary": "Routine annual exam. All vitals within normal range."
        }
      ]
    }
  }
}

Comprehensive Example

Full usage with multiple clinical data sources:

{
  "fullName": "Jane Doe",
  "birthDate": "1985-05-15",
  "phone": "6425482447",
  "address": "123 Main Street, City",
  "signedConsent": { "signed": true, "date": "2025-08-01" },
  "extraData": {
    "medical_practice": "Internal Medicine",
    "patient_medical_notes": {
      "notes": [
        {
          "consultation": "Endocrinology",
          "date": "2024-11-01",
          "url": "https://ehr.example.com/notes/12345",
          "summary": "HbA1c at 7.2%. Adjusted metformin dosage."
        }
      ]
    },
    "allergies": ["Penicillin", "Sulfonamides"],
    "active_medications": [
      {"name": "Metformin", "dose": "1000mg", "frequency": "twice daily"},
      {"name": "Lisinopril", "dose": "10mg", "frequency": "once daily"}
    ],
    "lab_results": {
      "date": "2024-10-28",
      "values": {
        "glucose_fasting": "142 mg/dL",
        "HbA1c": "7.2%",
        "creatinine": "0.9 mg/dL"
      }
    },
    "chronic_conditions": ["Type 2 Diabetes", "Hypertension"]
  }
}

The extraData Field

The extraData field is a flexible Record<string, unknown> that accepts any key-value structure. This is where you provide the clinical context that SofIA will use during the consultation.

Common fields used in extraData:

Field	Description
medical_practice	The doctor’s specialty (e.g., “Cardiology”, “Pediatrics”). Helps SofIA tailor responses to the clinical context
patient_medical_notes	Previous consultation notes. Include url fields if you want SofIA to cite the source
allergies	Known allergies for safety cross-referencing
active_medications	Current medications for interaction checking
lab_results	Recent laboratory values
chronic_conditions	Ongoing medical conditions

Include a url field in medical notes if you want SofIA to cite the data source when guiding the doctor. SofIA will reference the URL in its responses so the doctor can verify the original record.

Passing patientdata to the Component

As HTML Attribute

Since patientdata is a JSON type, it is automatically parsed by the SDK:

<sofia-sdk
  apikey="sk-your-api-key-here"
  baseurl="https://api.example.com/v1"
  wssurl="wss://ws.example.com"
  userid="dr-smith-789"
  patientid="patient-123"
  patientdata='{
    "fullName": "Jane Doe",
    "birthDate": "1985-05-15",
    "extraData": {
      "medical_practice": "Cardiology"
    }
  }'
></sofia-sdk>

Programmatically (JavaScript)

const sofiaElement = document.querySelector('sofia-sdk');
const patientData = {
  fullName: "Jane Doe",
  birthDate: "1985-05-15",
  extraData: {
    medical_practice: "Cardiology",
    allergies: ["Penicillin"]
  }
};

sofiaElement.setAttribute('patientdata', JSON.stringify(patientData));

React

const [patientData, setPatientData] = useState({
  fullName: "Jane Doe",
  birthDate: "1985-05-15",
  extraData: { medical_practice: "Cardiology" }
});

return (
  <sofia-sdk
    apikey="YOUR_API_KEY"
    baseurl="https://api.example.com/v1"
    wssurl="wss://ws.example.com"
    userid="dr-smith-789"
    patientid="patient-123"
    patientdata={JSON.stringify(patientData)}
  />
);

Limits and Validation

Rule	Details
Maximum size	100 KB
Error on exceed	The component rejects with error: "patientData exceeds 100 kB"
Format	Must be valid JSON (or a JavaScript object when passed programmatically)
Required fields	None — all fields are optional

Automatic Anonymization

SofIA automatically anonymizes the following personal fields before sending data to the AI engine:

• fullName
• birthDate
• phone
• address

These values are replaced with neutral placeholders during AI processing and restored in the final output. This ensures that personally identifiable information (PII) never reaches the AI model directly.

Data inside extraData is not automatically anonymized. Avoid placing raw PII (social security numbers, government IDs, etc.) in extraData fields. Use anonymized identifiers when possible.

Next Steps

1. Integrate with your framework
2. Design clinical data schemas
3. Test your integration