Integration Guide
Everything you need to integrate Healix into your healthcare application
Quick Start
Get up and running with Healix in minutes. Follow these steps to integrate our platform into your application.
Install the SDK
Choose your preferred language and install our SDK using your package manager.
npm install @healix/sdkInitialize the Client
Create a new Healix client instance with your API key. You can find your API key in the Developer Sandbox.
import { Healix } from '@healix/sdk';
const client = new Healix({
apiKey: 'YOUR_API_KEY',
environment: 'production' // or 'sandbox' for testing
});Connect a Device
Generate an authorization URL for a user to connect their device. This example shows how to connect a Fitbit device.
// Generate an authorization URL
const authUrl = await client.devices.getAuthorizationUrl({
provider: 'fitbit',
redirectUri: 'https://your-app.com/callback'
});
// Redirect the user to authUrl to authorize your app
// Handle the callback
app.get('/callback', async (req, res) => {
const { code } = req.query;
// Exchange the code for an access token
const user = await client.devices.completeAuthorization({
code,
redirectUri: 'https://your-app.com/callback'
});
// User is now connected
console.log('Connected user:', user.id);
});Fetch Health Data
Once a user has connected their device, you can fetch their health data using our API.
// Fetch activity data
const activityData = await client.users.getHealthData({
userId: 'user_123',
dataType: 'activity',
startDate: '2023-01-01',
endDate: '2023-01-31'
});
console.log('Activity data:', activityData);
// Fetch heart rate data
const heartRateData = await client.users.getHealthData({
userId: 'user_123',
dataType: 'heartRate',
startDate: '2023-01-01',
endDate: '2023-01-31'
});
console.log('Heart rate data:', heartRateData);Authentication
Healix uses API keys for authentication and OAuth 2.0 for device authorization. Here's how to implement both.
API Key Authentication
All requests to the Healix API must include your API key for authentication. Your API key is used to identify your application and track API usage.
import { Healix } from '@healix/sdk';
// Initialize with API key
const client = new Healix({
apiKey: 'YOUR_API_KEY'
});
// The SDK will automatically include your API key in all requestsOAuth 2.0 Device Authorization
To access user data from connected devices, you'll need to implement OAuth 2.0 authorization. This allows users to grant your application permission to access their data.
OAuth 2.0 Flow
Generate Authorization URL
Your app generates an authorization URL for the specific provider (e.g., Fitbit, Garmin).
User Authorization
The user is redirected to the provider's authorization page where they grant permission.
Callback with Authorization Code
The provider redirects back to your app with an authorization code.
Exchange Code for Access Token
Your app exchanges the code for an access token that can be used to access the user's data.
// Step 1: Generate authorization URL
const authUrl = await client.devices.getAuthorizationUrl({
provider: 'fitbit',
redirectUri: 'https://your-app.com/callback',
scope: ['activity', 'heartrate', 'sleep'] // Optional: specify scopes
});
// Step 2: Redirect user to authorization URL
// In a web application:
res.redirect(authUrl);
// Step 3 & 4: Handle callback and exchange code for token
app.get('/callback', async (req, res) => {
const { code } = req.query;
try {
// Exchange code for access token
const user = await client.devices.completeAuthorization({
code,
redirectUri: 'https://your-app.com/callback'
});
// Store the user ID for future requests
// The SDK handles token storage and refresh automatically
saveUserIdToDatabase(user.id);
res.send('Device connected successfully!');
} catch (error) {
console.error('Authorization error:', error);
res.status(500).send('Failed to connect device');
}
});Device Integration
Healix supports integration with 100+ wearable devices and health apps. Here's how to connect and retrieve data from these devices.
Supported Devices
Healix supports a wide range of wearable devices and health apps, including:
Connecting Devices
To connect a device, you'll need to implement the OAuth flow described in the Authentication section. Here's a specific example for connecting a Fitbit device:
// Generate authorization URL for Fitbit
const authUrl = await client.devices.getAuthorizationUrl({
provider: 'fitbit',
redirectUri: 'https://your-app.com/callback',
scope: ['activity', 'heartrate', 'sleep', 'weight']
});
// Redirect user to the authorization URL
// After authorization, handle the callback
app.get('/callback', async (req, res) => {
const { code } = req.query;
// Exchange code for access token
const user = await client.devices.completeAuthorization({
code,
redirectUri: 'https://your-app.com/callback'
});
// Store the user ID for future requests
console.log('Connected user:', user.id);
// You can now fetch data for this user
res.send('Fitbit connected successfully!');
});Fetching Device Data
Once a device is connected, you can fetch various types of health data. Here are some examples:
// Fetch activity data for a user
const activityData = await client.users.getHealthData({
userId: 'user_123',
dataType: 'activity',
startDate: '2023-01-01',
endDate: '2023-01-31'
});
console.log('Steps:', activityData.steps);
console.log('Distance:', activityData.distance);
console.log('Calories:', activityData.calories);
console.log('Active Minutes:', activityData.activeMinutes);Data Synchronization
Healix automatically syncs data from connected devices. You can also manually trigger a sync:
// Trigger a manual sync for a user's device
const syncResult = await client.devices.syncData({
userId: 'user_123',
provider: 'fitbit'
});
console.log('Sync status:', syncResult.status);
console.log('Last synced:', syncResult.lastSynced);
// You can also set up webhook notifications for new data
// See the Webhooks section in the documentationEHR Integration
Healix provides seamless integration with major Electronic Health Record (EHR) systems, allowing you to access and unify patient data.
Supported EHR Systems
Healix supports integration with major EHR systems, including:
Connecting to EHR Systems
Connecting to an EHR system requires FHIR API credentials and proper authorization. Here's how to set up an EHR connection:
// Connect to an EHR system
const ehrConnection = await client.ehr.connect({
system: 'epic',
organizationId: 'org_123',
credentials: {
clientId: 'YOUR_CLIENT_ID',
clientSecret: 'YOUR_CLIENT_SECRET',
apiEndpoint: 'https://fhir.epic.com/api/FHIR/R4'
},
scopes: ['patient/*.read', 'medication.read']
});
console.log('EHR connection status:', ehrConnection.status);
console.log('EHR connection ID:', ehrConnection.id);Fetching Patient Data
Once connected to an EHR system, you can fetch various types of patient data:
// Fetch patient demographics
const patientData = await client.ehr.getPatient({
ehrConnectionId: 'ehr_conn_123',
patientId: 'patient_456'
});
console.log('Patient Name:', patientData.name);
console.log('Date of Birth:', patientData.dateOfBirth);
console.log('Gender:', patientData.gender);
console.log('Contact Info:', patientData.contact);Unified Patient Data
One of the key benefits of Healix is the ability to unify data from both EHR systems and wearable devices. Here's how to access unified patient data:
// Fetch unified patient data
const unifiedData = await client.patients.getUnifiedData({
patientId: 'patient_456',
dataTypes: ['vitals', 'medications', 'activity', 'sleep'],
startDate: '2023-01-01',
endDate: '2023-01-31'
});
// Access EHR data
console.log('Vitals:', unifiedData.vitals);
console.log('Medications:', unifiedData.medications);
// Access wearable device data
console.log('Activity:', unifiedData.activity);
console.log('Sleep:', unifiedData.sleep);
// Unified insights
console.log('Insights:', unifiedData.insights);Best Practices
Follow these best practices to ensure a smooth integration with Healix.
Security
- Never expose your API key in client-side code
- Implement proper authentication for your application
- Use HTTPS for all API requests
- Securely store user tokens and sensitive data
Performance
- Use pagination for large data sets
- Implement caching for frequently accessed data
- Use webhooks for real-time updates instead of polling
- Specify only the data types you need in API requests
User Experience
- Implement a smooth OAuth flow with clear instructions
- Provide feedback during data synchronization
- Allow users to disconnect devices easily
- Be transparent about data usage and privacy
Development
- Use the sandbox environment for testing
- Implement proper error handling
- Keep your SDK up to date
- Follow our versioning guidelines for API endpoints
Ready to Get Started?
Join hundreds of healthcare innovators who are building the future with Healix. Integrate in days, not months.