AI Summary Integration

This guide describes how to integrate with HAMI to automatically receive AI-generated patient summaries via API callbacks. This enables your system to receive updated patient intake information as patients interact with HAMI.

Overview

HAMI can automatically post AI-generated summaries to your facility’s designated endpoint whenever a patient completes or updates their intake session. This push-based integration ensures your system always has the latest patient information without requiring manual data retrieval.

Key Benefits

• Real-Time Updates: Receive summaries automatically as patients complete their intake
• Progressive Enhancement: Get updated summaries as patients provide additional information
• Seamless Integration: Minimal changes to your existing workflow
• Automated Workflow: No manual intervention required to transfer patient data
• Pre-Visit Preparation: Physicians can review summaries before patient arrival

How It Works

When a patient interacts with HAMI for medical intake, an AI-generated summary is created based on their responses. This summary is automatically posted to your facility’s API endpoint. If the patient interacts with HAMI multiple times (e.g., to add more information or clarify details), HAMI will post an enhanced summary with each update, ensuring your system always has the most current information.

Integration Flow

Step 1: Patient Completes Intake

• The patient accesses the HAMI intake URL and completes their medical history
• HAMI’s AI engine processes the conversation and generates a comprehensive summary
• The summary includes chief complaints, medical history, medications, allergies, and other relevant clinical information

Step 2: Automated Summary Posting

• Once the patient completes or updates their intake session, HAMI automatically posts the AI summary to your configured endpoint
• The summary is sent as a JSON payload via HTTP POST request
• Multiple summaries may be posted for the same appointment as patients can interact with HAMI multiple times
• Each subsequent posting contains an enhanced version of the summary with newly gathered information

API Endpoint Configuration:

Your facility must provide a publicly accessible HTTPS endpoint:

POST https://your-facility-api.com/api/ai-summary

Summary Payload Structure:

HAMI will send a JSON payload containing:

• Appointment identifiers: Both HAMI’s appointment ID and your facility’s ID (if provided)
• Patient information: Demographics and contact details
• AI-generated summary: Structured clinical information in a standardized format
• Timestamp: When the summary was generated
• Version information: To track multiple summary updates

Note: Detailed payload format specifications and sample payloads are provided separately in the integration documentation package.

Step 3: Receiving and Processing Summaries

Your endpoint should:

1. Validate the request using the API key authentication mechanism (see Security section)
2. Parse the JSON payload to extract summary information
3. Match the appointment using either the HAMI appointment ID or your facility’s appointment ID
4. Update your patient record with the summary information
5. Handle duplicate/updated summaries appropriately (newer summaries supersede previous ones)
6. Return appropriate HTTP response codes:
   • 200 OK: Summary successfully received and processed
   • 401 Unauthorized: Invalid or missing API key
   • 400 Bad Request: Invalid payload format
   • 500 Internal Server Error: Processing error on your end

Important Considerations:

• Multiple Summary Updates: Since patients may interact with HAMI multiple times, your system should be designed to handle multiple summary postings for the same appointment. Each new summary represents the most current and complete information.
• Idempotency: Implement your endpoint to be idempotent where possible, as network issues may occasionally result in duplicate transmissions.
• Data Validation: Always validate incoming data against your business rules before storing in your system.

Technical Requirements

For Your Development Team

1. Public HTTPS Endpoint: Deploy a publicly accessible API endpoint to receive summary postings
2. API Key Validation: Implement API key validation in request headers for security
3. JSON Processing: Ability to parse and process JSON payloads in the specified format
4. Appointment Mapping Logic: Implement logic to associate received summaries with the correct appointment
5. Data Storage: Update your database schema if needed to accommodate AI summary data
6. Error Handling: Implement robust error handling and logging for debugging
7. Version Management: Handle multiple summary versions for the same appointment

Payload Format

HAMI provides two reference documents for integration:

1. Format Template: A schema definition file that describes all possible fields and their data types
2. Sample Payload: A real-world example of a summary payload from HAMI

These documents must be reviewed and your endpoint must be designed to accept payloads in the specified format. Contact your integration partner to obtain these documents.

Security & Authentication

API Key Authentication (Recommended)

Since your endpoint must be publicly accessible, proper authentication is critical to ensure that only HAMI can post summaries to your system.

Implementation Steps:

1. Generate API Key: Create a secure, random API key (minimum 32 characters, alphanumeric with special characters recommended)
2. Share with HAMI: Provide this API key to HAMI during integration setup
3. Configure HAMI: HAMI will include this key in the HTTP headers of every summary posting request
4. Validate Requests: Your endpoint must validate that incoming requests contain the correct API key

Request Header Format:

POST https://your-facility-api.com/api/ai-summary
Headers:
  Content-Type: application/json
  X-API-Key: your-secure-api-key-here

Body:
  { ... summary payload ... }

Security Best Practices:

• Store the API key securely (use environment variables or secure key management systems)
• Never commit API keys to version control systems
• Rotate API keys periodically (coordinate with HAMI for updates)
• Use HTTPS only (never HTTP) to protect data in transit
• Implement rate limiting to prevent abuse
• Log all authentication failures for security monitoring
• Consider implementing IP whitelisting as an additional security layer

Data Security

• Encryption in Transit: All API communications must use HTTPS/TLS 1.2 or higher
• Encryption at Rest: Store received summaries in encrypted databases
• Access Control: Restrict access to summary data based on role-based permissions
• Audit Logging: Maintain audit logs of all summary receptions and access
• HIPAA Compliance: Ensure your endpoint and data handling processes are HIPAA compliant
• Data Retention: Implement appropriate data retention and deletion policies

Best Practices

Endpoint Design

• Performance: Design your endpoint to respond quickly (within 5 seconds) to avoid timeouts
• Asynchronous Processing: Consider processing summaries asynchronously if your workflow is complex
• Transaction Management: Use database transactions to ensure data consistency
• Monitoring: Implement health checks and monitoring for your endpoint
• Scaling: Ensure your endpoint can handle peak loads during busy periods

Data Handling

• Merge Strategy: When receiving updated summaries, decide whether to:
  • Replace the previous summary entirely
  • Merge new information with existing data
  • Maintain version history of all summaries
• Data Normalization: Map HAMI’s summary format to your internal data structures
• Validation Rules: Implement business logic to validate incoming data
• Conflict Resolution: Define how to handle conflicts between existing patient data and new summaries

Error Recovery

• Logging: Log all incoming requests, successes, and failures with sufficient detail
• Alerting: Set up alerts for repeated failures or unusual patterns
• Retry Mechanism: While HAMI may implement retries, design your endpoint to handle duplicate requests gracefully
• Fallback Procedures: Establish manual procedures for when automated posting fails