Frequently Asked Questions

Common questions about SofIA SDK configuration, data handling, clinical coding, and technical support

Implementation and Configuration

How do I get an API key for SofIA?

Email [e-mail] with your company name, project description, and expected usage. The Omniloy team will provide your apikey. For newer keys the SDK resolves the endpoint automatically, so no baseurl is needed; other keys also come with a baseurl — Omniloy tells you which applies to yours. Typical response time is 1-2 business days. See the Quickstart for full details.

What's the difference between sandbox and production?

• Sandbox: Testing environment with simulated data, ideal for development and integration. No usage-based billing. AI responses may use sample data.
• Production: Real environment with full medical AI processing and usage-based billing. Requires valid SSL certificate and production API key.

The only code change needed is swapping your apikey — Omniloy gives you a separate key for each environment. If your key requires a baseurl, swap that too. See How do I migrate from sandbox to production? below.

Can I use SofIA without report generation?

Yes, simply omit the template and templateid properties. SofIA will automatically operate in chat-only mode without the generate button. Ideal for text-based queries or integrations with existing systems.

How do I migrate from sandbox to production?

1. Replace the apikey with your production credentials — Omniloy issues a separate key per environment
2. If your key requires a baseurl, update it to the production endpoint
3. Validate configuration with a test query
4. Implement appropriate monitoring and logging

Data and Integration

Where is processed data stored?

SofIA does not persist clinical data. The generated report is delivered through the handleReport callback and it’s your application’s responsibility to store it in your EHR or management system.

How do I reduce the size of patientData?

• Include url fields in patient_medical_notes entries to reference external records instead of embedding the entire history (see Patient Data)
• Include only information relevant to the current consultation
• Segment data by specialty or time period

What format should JSON schemas have?

Schemas must follow JSON Schema Draft-07. Always include:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "diagnosis": { "type": "string" }
  },
  "required": ["diagnosis"]
}

Clinical Coding

How does automatic coding work?

Automatic clinical coding (ICD-10, SNOMED CT, LOINC) is available through the SofIA API (Codify). In the SDK, you can enable coding references in your template schema using the source property — see Clinical data schemas for details.

Can I customize the terminologies used?

Yes. In the SDK, you can request a terminology directly in a field’s description (e.g. “with its ICD-10 code”), or code against a custom master by setting the field’s source. Masters are provisioned per account — contact [e-mail] to have your custom master created and receive its source value. See Clinical data schemas for details. In the API, pass the desired terminology in your request payload — see the API overview.

How do I validate the accuracy of generated codes?

• Always implement medical review for critical codes — AI-generated codes should be verified by a clinician before submission
• Configure "required" fields in your JSON Schema to ensure key codes are always present
• Use the handleReport callback to run custom validation logic before persisting to your EHR
• Enable debug="true" during development to inspect the full report payload

Performance and Scalability

What are the usage limits?

• Maximum payload: 100 KB for template and 100 KB for patientdata
• Simultaneous sessions: Depends on your subscription plan — contact [e-mail] for details
• Rate limiting: Configured per API key based on your contract. If you receive HTTP 429 responses, you’ve exceeded your rate limit

How do I optimize performance?

• Use concise and specific JSON schemas
• Reduce the size of template and patientdata to minimize processing time
• Use debug="true" to identify bottlenecks in the browser console
• Pre-load relevant data when possible

Technical Support

What browsers are compatible?

SofIA is compatible with modern browsers that support WebRTC and WebSockets:

• Chrome 80+
• Firefox 75+
• Safari 13+
• Edge 80+

Is there additional documentation available?

• Framework-specific integration guides (Vanilla JS, React, Angular)
• Complete code examples on GitHub: sofia-sdk-examples
• Complementary REST API documentation: SofIA API