Required Properties

Mandatory configuration for SofIA SDK

The SofIA SDK requires just three properties to connect: apikey, userid, and patientid. The component validates their presence and type before establishing the connection. baseurl is only required for some keys — see Connection and authentication below.

Quick Reference

All SofIA SDK properties in a single table. For detailed documentation, see Connection and authentication and Optional Properties.

Property	Type	Default	Status	Description
apikey	string	—	Required	Authentication key from Omniloy
userid	string	—	Required	Internal surrogate identifier of the healthcare professional (never an MRN or direct PII)
patientid	string	—	Required	Internal surrogate identifier of the patient for the session (never an MRN or direct PII)
baseurl	string	auto	Conditional	REST API endpoint (HTTPS). Optional for newer keys since 1.0.8 (auto-resolved); required otherwise
template	object	—	Optional	JSON Schema Draft-07 defining the clinical data structure. Enables report generation when used with templateid
templateid	string	—	Optional	Integrator-defined identifier for the template. Required with template to enable report generation
isopen	boolean	true	Optional	Component visibility state (open/closed)
handleReport	function	—	Optional	Callback that receives the generated clinical report
setIsOpen	function	—	Optional	Callback for visibility change events
setGetLastReport	function	—	Optional	Callback that receives a function to retrieve the last report
onReportApply	function	—	Optional	Receives the curated report from the insertion preview modal
updateTemplate	function	—	Optional	Feeds existing EMR field content into generation (pre-fill)
insertionPreviewClassNames	object	—	Optional	Class-name overrides for the insertion preview modal
templateExtras	object	—	Optional	JSON Schema of action categories; enables the Extras buttons together with handleExtras. template-extras attribute on the web component
handleExtras	function	—	Optional	Receives the clinical actions extracted per category, pass-through (Extras)
patientdata	string | object	—	Optional	Contextual patient information for enriched processing
language	string	"es"	Optional	Interface language ("es" or "en")
debug	boolean	false	Optional	Enables detailed console logging
wssurl	string	—	Deprecated	Ignored since 1.0.7 — the transcriber URL now comes from the settings API
toolsargs	object	—	Deprecated	Use template instead
isonlychat	boolean	—	Deprecated	Auto-detected — omit template/templateid for chat-only
disableactions	boolean	—	Deprecated	Do not mount the component instead
disablegenerate	boolean	—	Deprecated	Omit template/templateid instead
sofiatitle	string	—	Deprecated	Title is always “SofIA”
isscreenloading	boolean	—	Deprecated	Not available in Chat-based UI
transcriptorselectvalues	array	—	Deprecated	No effect
render-report-content	function	—	Deprecated	Not available in Chat-based UI
handleFill	function	—	Deprecated	Not available in Chat-based UI

For migration guidance on deprecated properties, see the Migration Guide.

Connection and authentication

The apikey is the only connection property you always need. For newer keys, the SDK selects the endpoint automatically — so you do not pass baseurl.

Property	Type	Description
apikey	string	Authentication key from Omniloy. For newer keys the correct endpoint is selected automatically
baseurl	string	REST API endpoint (HTTPS). Optional for newer keys; required otherwise

Does my key need baseurl? Newer keys don’t — the SDK resolves the endpoint for you, so you can omit baseurl. Other keys do — keep passing the baseurl value Omniloy assigned you. If you’re unsure, Omniloy will tell you which applies to your key.

wssurl is deprecated and ignored since v1.0.7. The transcription WebSocket URL is now provided automatically by the settings API. Passing wssurl has no effect; you can safely remove it from your integration.

Session Identifiers

Property	Type	Description
userid	string	Internal surrogate identifier of the healthcare professional in the EHR/HIS system
patientid	string	Internal surrogate identifier of the patient for the current session

Use internal surrogate identifiers for userid and patientid — never a medical record number (MRN) or other direct patient/professional identifier. Unlike patientdata, these values are sent without anonymization.

userid best practices

• Use persistent, unique identifiers
• Avoid personally identifiable information
• Maintain consistency across sessions
• Consider using professional license numbers or internal IDs

patientid important notes

• Must be unique within your system
• Should not contain direct personal identifiers
• Can be changed dynamically for different consultations
• Must comply with data protection regulations

Changing patientid triggers a full session reset. When you update patientid dynamically, the SDK clears the chat history, closes the current WebSocket connection, and starts a completely new session. The previous conversation context is not carried over to the new patient. Always ensure any pending report generation has completed before switching patients.

Report Generation

These properties enable report generation. When both template and templateid are provided, the generate button becomes available in the interface. Without them, SofIA operates in chat-only mode automatically.

Property	Type	Required	Description
template	object	Optional	Complete JSON Schema Draft-07 schema that defines the clinical data structure to generate. Required together with templateid to enable report generation. Pass as a JSON string in HTML attributes or as a JavaScript object programmatically
templateid	string	Optional	Integrator-defined identifier for the template. Each unique template should have its own templateid. Required together with template to enable report generation

Deprecated: The toolsargs property has been renamed to template. Use template instead. toolsargs will be removed in v2.0.

template (Optional — required for report generation)

JSON Schema defining the structure for clinical data capture. When provided together with templateid, enables the report generation feature and shows the generate button in the interface.

<sofia-sdk template='{"$schema":"http://json-schema.org/draft-07/schema#","title":"Medical Consultation"}'></sofia-sdk>

Schema requirements:

• Must be valid JSON Schema Draft-07
• Must include $schema property
• Should define required fields appropriately
• Must not exceed 100KB in size

Example for general consultation:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "General Medical Consultation",
  "type": "object",
  "properties": {
    "chief_complaint": {
      "type": "string",
      "description": "Primary reason for visit"
    },
    "diagnosis": {
      "type": "string",
      "description": "Primary diagnosis"
    },
    "treatment_plan": {
      "type": "string",
      "description": "Recommended treatment"
    }
  },
  "required": ["chief_complaint", "diagnosis"]
}

For complex schemas, set the template programmatically via JavaScript instead of inline HTML to avoid JSON escaping issues. See Templates — Passing templates.

templateid (Optional — required for report generation)

Integrator-defined identifier that you assign to each template. Must be provided together with template to enable report generation.

<sofia-sdk templateid="soap-general-v1"></sofia-sdk>

How it works:

• You choose the templateid value — it is not provided by Omniloy
• Each unique template must have its own templateid
• SofIA uses this ID to associate configurations and report history on the server
• If you reuse the same templateid with a different template schema, the previous configuration will be overwritten

Using the same templateid for different template schemas will overwrite the previous configuration. Always assign a distinct templateid to each template you use.

Naming examples:

• "soap-general-v1" — SOAP notes for general practice
• "emergency-triage-v2" — emergency department triage
• "cardiology-consult-v1" — cardiology consultations
• "my-clinic-intake-form" — custom intake form for your clinic

Automatic Validation

The SofIA SDK component performs automatic validation of the required configuration properties:

• Type verification: Confirms that each property has the correct type
• URL validation: Verifies that the resolved baseurl uses the secure HTTPS protocol

Validation Error Messages

When validation fails, the SofIA SDK will display detailed error messages in the browser console and prevent the component from mounting. This ensures that integration issues are identified early in the development process.

Example validation error output:

[Sofia SDK] Configuration Error - Missing or invalid required properties:

  • apikey: API key for authentication
  • userid: Unique identifier of the healthcare professional in the EHR/HIS system
  • patientid: Unique identifier of the patient in the EHR/HIS system
  • baseurl: API base URL (only required for keys that need it)
    Current value: "INVALID_API_KEY"
    Current value: "INVALID_USER_ID"
    Current value: "INVALID_PATIENT_ID"

Component will not mount until all required properties are provided.
Documentation: https://omniloy.mintlify.app/en/sdk/required-properties

Error message components:

• Property name: Identifies which property failed validation
• Description: Explains the purpose of each property
• Current value: Shows the invalid value that was provided (when applicable)
• Documentation link: Provides direct access to this reference guide

Component behavior during validation errors:

• The SofIA SDK component will not establish connections
• No medical data processing will occur
• The component remains in a safe, non-functional state
• Error messages are logged to help developers identify and resolve issues quickly

For comprehensive troubleshooting of validation errors, see our troubleshooting guide.

Minimal example (chat-only mode)

With a newer key, apikey, userid, and patientid are all you need:

<sofia-sdk
  apikey="your-api-key"
  userid="user_12345"
  patientid="patient_67890"
></sofia-sdk>

Does your key require a baseurl? Add the one Omniloy assigned you:

<sofia-sdk
  apikey="your-legacy-key"
  baseurl="https://your-assigned-endpoint/v1"
  userid="user_12345"
  patientid="patient_67890"
></sofia-sdk>

If any required property is missing or invalid, the component will show an error and will not connect to SofIA services.

With report generation

To enable report generation, add both template and templateid:

<sofia-sdk
  apikey="your-api-key"
  userid="user_12345"
  patientid="patient_67890"
  templateid="soap-notes-v1"
  template='{
    "$schema": "http://json-schema.org/draft-07/schema#",
    "title": "Clinical Notes",
    "type": "object",
    "properties": {
      "diagnosis": {"type": "string", "description": "Primary diagnosis"}
    },
    "required": ["diagnosis"]
  }'
></sofia-sdk>

Complete Configuration Example

<sofia-sdk
  apikey="your-api-key"
  userid="dr-garcia-456"
  patientid="patient-123"
  templateid="emergency-triage-v2"
  template='{
    "$schema": "http://json-schema.org/draft-07/schema#",
    "title": "Emergency Consultation",
    "type": "object",
    "properties": {
      "triage_level": {
        "type": "string",
        "enum": ["1", "2", "3", "4", "5"],
        "description": "Emergency triage level"
      },
      "chief_complaint": {
        "type": "string",
        "description": "Main complaint"
      },
      "vital_signs": {
        "type": "object",
        "properties": {
          "blood_pressure": {"type": "string"},
          "heart_rate": {"type": "number"},
          "temperature": {"type": "number"}
        }
      },
      "diagnosis": {
        "type": "string",
        "description": "Emergency diagnosis"
      },
      "disposition": {
        "type": "string",
        "enum": ["discharge", "admit", "transfer", "observe"],
        "description": "Patient disposition"
      }
    },
    "required": ["triage_level", "chief_complaint", "diagnosis", "disposition"]
  }'>
</sofia-sdk>

Dynamic Configuration

Updating properties programmatically

const sofiaElement = document.querySelector('sofia-sdk');

// Update patient for new consultation
sofiaElement.setAttribute('patientid', 'patient-456');

// Update schema for different specialty
const cardiologySchema = {
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "Cardiology Consultation",
  "type": "object",
  "properties": {
    "heart_rhythm": {
      "type": "string",
      "enum": ["normal", "irregular", "fast", "slow"]
    },
    "blood_pressure": {
      "type": "string",
      "pattern": "^\\d{2,3}/\\d{2,3}$"
    },
    "ecg_findings": {
      "type": "string"
    }
  },
  "required": ["heart_rhythm", "blood_pressure"]
};

sofiaElement.setAttribute('template', JSON.stringify(cardiologySchema));

Framework-specific configuration

React

const [patientId, setPatientId] = useState('patient-123');
const [template, setTemplate] = useState({
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "Clinical Notes",
  "type": "object",
  "properties": {
    "diagnosis": { "type": "string", "description": "Primary diagnosis" }
  },
  "required": ["diagnosis"]
});
const [templateId, setTemplateId] = useState('soap-general-v1');

return (
  <sofia-sdk
    apikey="your-api-key"
    userid="dr-smith-789"
    patientid={patientId}
    templateid={templateId}
    template={JSON.stringify(template)}
  />
);

Angular

export class AppComponent {
  apiKey = 'your-api-key';
  userId = 'dr-lopez-456';
  patientId = 'patient-789';
  templateId = 'soap-general-v1';
  schema = {
    "$schema": "http://json-schema.org/draft-07/schema#",
    "title": "Clinical Notes",
    "type": "object",
    "properties": {
      "diagnosis": { "type": "string", "description": "Primary diagnosis" }
    },
    "required": ["diagnosis"]
  };
  templateJson = JSON.stringify(this.schema);
}

Validation

Property validation checklist

• apikey is valid and not expired
• baseurl uses HTTPS protocol (only needed for keys that require it)
• userid is unique and consistent
• patientid is unique for the consultation
• templateid is unique per template and consistent across sessions (if using report generation)
• template is valid JSON Schema Draft-07 (if using report generation)
• All required properties are present
• No properties exceed size limits

Next Steps

After configuring required properties:

1. Configure optional properties
2. Design clinical data schemas
3. Implement in your framework