Healthie
Connect your Gravity Rail workspace to Healthie to sync appointments, match members to patients, and access provider information -- all from one place.
Healthie is an EHR and practice management platform used by healthcare organizations for scheduling, patient records, and care delivery. This integration bridges the gap between your Gravity Rail workflows and your Healthie practice data, so your team can coordinate care without switching between systems.
What the Integration Does
- Appointment sync -- Pull Healthie appointments into Gravity Rail calendars, linked to a specific provider. Appointment types, statuses, and scheduling details stay in sync.
- Member-patient matching -- Find Gravity Rail members who correspond to Healthie patients by email or phone number, then link them so both systems reference the same person.
- Provider directory -- Browse the providers in your Healthie organization directly from Gravity Rail.
- Appointment types -- Import Healthie appointment types as calendar event types, so your calendars reflect the same categories your practice uses.
Prerequisites
Before you connect, you need:
- A Healthie account with API access. Your Healthie organization must have API keys enabled. You can find or generate your API key in your Healthie account under Settings > API.
- The
ehr_healthiefeature flag enabled for your workspace. Contact your Gravity Rail account team if you do not see Healthie in your App Connections directory. - Admin permissions in your Gravity Rail workspace. Configuring the Healthie connection requires Apps Write. Linking and refreshing calendars also requires Calendars Admin and permission to manage that calendar.
Connecting to Healthie
1. Open the App Connections Directory
Navigate to App Connections in the sidebar. Find Healthie in the directory and click Add.
2. Enter Your API Key
In the configuration dialog:
- API Key -- Paste the API key from your Healthie account (Settings > API). This key is encrypted at rest and never stored in plaintext.
- Base URL (optional) -- Leave this blank to use the standard Healthie production API. If your organization uses Healthie's staging environment, enter
https://staging-api.gethealthie.com/graphqlinstead.
Click Connect. Gravity Rail tests the connection immediately by verifying your API key against the Healthie API. If the test succeeds, you see a green Connected badge. Open Setup to check the Healthie user associated with the key.
3. Verify the Connection
After connecting, the Healthie management page shows the Healthie logo and the connection status at the top and three tabs:
| Tab | What It Shows |
|---|---|
| Members | Workspace members linked to Healthie patients, with tools to find new matches |
| Calendar Sync | Calendars linked to Healthie providers, with sync controls |
| Setup | Connected Healthie user and API key details; Update credentials opens the configuration dialog |
The page opens on Members. To check the Healthie user associated with the key, open Setup. If the status shows Error, open Setup, click Update credentials, and enter a valid API key. A replacement key is tested before it replaces the saved connection. To switch to another Healthie account or API URL, unlink its calendars first.
Calendar Sync
Calendar sync pulls a Healthie provider's appointments into a Gravity Rail calendar. Each calendar is linked to one provider -- if you have multiple providers, link a separate calendar to each one.
Linking a Calendar to a Provider
- Go to the Calendar Sync tab on the Healthie management page, or open a calendar's settings page.
- Select a Calendar from the dropdown (only internal calendars that are not already linked to another source are available).
- Select a Healthie Provider from the dropdown. This list is populated directly from your Healthie organization.
- Click Link & Sync.
When you link a calendar, Gravity Rail:
- Imports the provider's appointment types from Healthie and creates matching calendar event types.
- Imports appointments from the past 30 days through the next 365 days, including cancelled appointments.
- Refreshes the linked calendar automatically every five minutes. Previously imported active appointments remain eligible for refresh when their dates change.
Each synced appointment appears as a calendar event with the appointment type name, scheduled time, duration, and status.
Appointment Status Mapping
Healthie appointment statuses map to Gravity Rail calendar event statuses:
| Healthie Status | Calendar Event Status |
|---|---|
| Confirmed | Confirmed |
| Checked-In | Confirmed |
| Occurred | Completed |
| No-Show | No Show |
| Cancelled | Cancelled |
| Late Cancellation | Cancelled |
| Re-Scheduled | Cancelled |
Manual Sync
Click Sync Now to refresh the linked calendar immediately. The panel shows the last successful sync time and flags when the latest sync needs attention. A partial sync reports how many appointments could not be imported; it does not replace the last successful sync time. Check the Healthie connection and retry. If another refresh is already running, the request returns a busy response (HTTP 409); wait for that refresh to finish before retrying.
If there are no calendars to link, use Manage calendars to create an internal calendar, then return to select the Healthie provider. Provider or calendar load errors show a retry action.
Unlinking a Calendar
Click Unlink next to a linked calendar to disconnect it from Healthie. The calendar reverts to an internal calendar. Previously synced events remain but are no longer updated from Healthie.
Member-Patient Matching
Member-patient matching (reconciliation) connects Gravity Rail members to their corresponding Healthie patient records. Once linked, a member carries a healthie:patient_id field that identifies them in both systems.
How Matching Works
Gravity Rail proposes a patient only when a search finds exactly one active Healthie patient with that contact detail. It uses two methods, in order:
- Email match -- The member's email address exactly matches one patient's email (case-insensitive).
- Phone match -- Used only when the member has no email on file, or the email search found no exact match. The member's phone number matches one patient's phone number, ignoring formatting such as dashes and spaces.
Only members who have an email or phone number on file are included in the search. Members already linked to a Healthie patient are excluded.
A member is left out of the results when two or more patients share the contact detail, or when the search fails or returns too many results to check. Being left out does not mean no patient exists. Archived patients are not searched, and phone search can miss a patient. Try again later if a search may have failed. To link a member who shares a contact detail with someone else, confirm the right patient in your records, then link that pair through the API.
Finding and Linking Matches
- Go to the Members tab on the Healthie management page.
- Click Link Members.
- In the dialog, click Find matches to start the search.
The results show each potential match as a card with the Gravity Rail member on the left and the Healthie patient on the right, along with the match type (email or phone). For each match, you can:
- Click Link to confirm the match and create the link.
- Click Link All to confirm all displayed matches at once.
Linking Patients from Their Appointments
A synced appointment shows its patient as an attendee only when that patient is linked to a member. To link patients whose appointments arrive without a member:
- Go to the Members tab on the Healthie management page.
- Click Link appointment patients.
- In the dialog, click Find matches.
The dialog checks up to 50 patients from your synced Healthie calendars who are not yet linked. For each one, it proposes the single member whose email address matches exactly (ignoring capital letters). Phone number is checked only when no member has that email. Members already linked to a Healthie patient are never proposed.
A patient is left out when two or more members share the contact detail, when the same member would match two patients in the list, or when the patient's details could not be read. Nothing is linked until you click Link or Link All. After you link a patient, the next calendar sync adds the member to that patient's appointments.
Viewing and Managing Linked Members
The Members tab displays all members currently linked to Healthie patients. Each row shows the member's name, contact information, and their Healthie patient ID. Click Unlink next to any member to remove the link.
Unlinking a member removes the healthie:patient_id field from that member. It does not delete any data in Healthie.
Provider Directory
The integration gives you read access to the providers (staff members) in your Healthie organization. Provider information is used in two places:
- Calendar sync -- When linking a calendar, you select which provider's appointments to sync.
- Appointment types -- You can view appointment types filtered by provider.
Provider data includes name and email. The provider list updates each time you open a page that uses it.
Current Limitations
This integration is in active development. Here is what is supported today and what is planned:
| Capability | Status |
|---|---|
| Pull appointments from Healthie into Gravity Rail calendars | Available |
| Automatic refresh every five minutes | Available |
| Import Healthie appointment types | Available |
| Match members to Healthie patients by email/phone | Available |
| Link and unlink members individually or in bulk | Available |
| View Healthie providers | Available |
| Push appointments from Gravity Rail to Healthie | Planned |
| Real-time sync via Healthie webhooks | Planned |
| AI assistant tools for Healthie data | Planned |
| Automatic webhook lifecycle management | Planned |
The integration uses API key authentication, not OAuth. This means there is one connection per workspace (not per user), and whoever generates the API key in Healthie determines the permissions available to the integration.
Troubleshooting
Connection shows "Error" status
Your API key may have been revoked or expired in Healthie. Open Setup, click Update credentials, and enter a fresh API key from Healthie Settings > API.
No providers appear in the dropdown
The API key may not have permission to list organization members in Healthie. Verify that the key belongs to an account with appropriate access in your Healthie organization.
Calendar sync shows 0 appointments after linking
Check the selected provider and confirm Healthie has appointments within the past 30 days or next 365 days. Also check whether the panel flags that sync needs attention. A connected API key confirms access to Healthie; it does not prove that calendar appointments imported successfully.
Member matching finds no results
Matching requires members to have an email or phone number that exactly matches a Healthie patient record. Check that your members have contact information populated and that the same contact details exist in Healthie. A member is also left out when their contact details match more than one patient, or when the search returned too many results or could not finish. Trying again helps only when a search could not finish.
"Healthie API request failed" error
This typically indicates a temporary issue communicating with the Healthie API. Wait a moment and try again. If the error persists, verify your API key is still valid and that the Healthie API is operational.
Previously linked member shows as unlinked
If a member's
healthie:patient_idfield was manually removed or if the Healthie connection was deleted and re-created, the link is lost. Use Link Members, then Find matches, to re-establish the link.
Tips
- Start by linking one provider's calendar to verify the sync before connecting additional providers.
- Use Link Members, then Find matches, after importing new members to quickly establish links to existing Healthie patients.
- After bulk-linking members, spot-check a few records to confirm the matches are correct before relying on the linked data in workflows.
- If your organization uses Healthie's staging environment for testing, configure the Base URL to point to the staging API before connecting production.