Skip to main content

Connect athenahealth (athenaOne)

Early access (beta). The athenahealth integration is available to pilot practices. Some capabilities are still being validated against athenahealth's production environment. Talk to your Gravity Rail representative before you rely on it for live patient care.

What You'll Accomplish​

By the end of this guide, your Gravity Rail workspace will be connected to your athenahealth (athenaOne) practice. Once connected, your AI agents can — for the members you explicitly link to a patient record:

  • Keep member profiles current by syncing patient demographics from athenaOne.
  • Optionally discover new patients — create a member for each new patient in chosen departments whose status you accept (off by default).
  • View a linked member's chart data during a conversation (demographics, recent encounters, care context) — read-only.
  • Book, reschedule, and cancel appointments in athenaOne.
  • Check insurance eligibility for a patient's coverage.
  • Write outreach documentation back to the chart — for example, a phone-message note summarizing an outreach call, which lands in your providers' standard athenaOne review queue.

Everything an agent can do is scoped to the single patient linked to the member it's talking to. Agents cannot browse or search your patient population (more on this below — it's a deliberate privacy protection).

What You'll Need​

  • A Gravity Rail workspace with admin access (you'll need permission to manage app connections).
  • An athenahealth practice on the athenaOne platform, and your practice ID (athenahealth also calls this the "Context ID").
  • Connection credentials for your practice, which your Gravity Rail representative will provide and help you configure. Setting up API access with athenahealth involves an application review on their side; your representative coordinates that with you.
  • A signed Business Associate Agreement (BAA). Because this integration moves Protected Health Information (PHI), a BAA must be in place before you connect a live production practice. Until the agreement is recorded, the connection is intentionally blocked from being created or enabled. Your representative will confirm when you're cleared.

Step 1: Open FHIR Connections​

athenahealth connects through Gravity Rail's FHIR Connections area.

  1. In the left sidebar, open Connections → FHIR Connections.
    • If you don't see it, the healthcare EHR feature isn't enabled for your workspace yet — ask your Gravity Rail representative to turn it on.
  2. Click New FHIR Connection in the top right.

This opens a short setup wizard.

Step 2: Choose athenahealth and enter your practice details​

The wizard walks you through a few steps:

  1. Select your EHR vendor. Choose Athena.
  2. Connection details:
    • Connection Name — a friendly label so you can tell connections apart (e.g., "Main Clinic — athenahealth").
    • FHIR Base URL — the athenahealth FHIR endpoint for your environment. Your Gravity Rail representative provides the exact value.
    • Practice ID — your athenahealth practice (Context) ID. Requests are automatically scoped to this practice.
  3. Credentials — enter the connection credentials your representative gave you. Requests to athenahealth are scoped to your practice automatically once these are in place.
  4. Settings — leave the request rate limit at its default unless your representative advises otherwise, then review the summary and create the connection.

Once created, the connection appears in your FHIR Connections list. You can also find it on the App Connections page under Healthcare Connections.

Use practice-owned credentials, not a personal login. As with any integration, tie the connection to your practice's API application rather than an individual's account so it keeps working as staff change.

Gravity Rail only reads or writes a patient's chart once you've explicitly linked that Gravity Rail member to their athenahealth patient record. There is no bulk import and no automatic matching — linking is deliberate and one member at a time (optional patient discovery, below, links only by the exact patient record athenahealth reports).

  1. Open the connection's detail page and go to the Members area.
  2. Find the patient by their athenahealth patient identifier (their patient ID / medical record number).
  3. Link that patient to the corresponding Gravity Rail member — either an existing member or a new one you create at link time.

The link is an exact identifier match: one member maps to exactly one patient. Gravity Rail never guesses a match from a similar name or date of birth, so there's no risk of accidentally attaching the wrong chart.

Optional: discover new patients automatically​

If your practice creates partial patient records in athenaOne (for example, prospective patients from a referral partner), patient discovery can create a Gravity Rail member for each new eligible patient and link it to that exact record. It is off until you turn it on, and it only applies to athenahealth connections.

Before you start, check with your Gravity Rail representative that:

  • your practice's BAA is recorded (discovery cannot be switched on until it is);
  • inbound Member sync is enabled on this connection's Sync settings;
  • this is the only Gravity Rail connection for your athenahealth practice.

To turn it on:

  1. Open the connection's Members tab and find the Patient discovery card.
  2. Switch on Enable discovery.
  3. Enter up to five Department IDs, separated by commas or spaces. Only patients registered in these departments are discovered.
  4. Enter the Accepted statuses — the exact status value (or values, separated by commas) your practice uses for the patients you want, for example the value athenaOne shows for a prospective patient. Case matters, and there is no default.
  5. Optionally pick a Default role for discovered members. Leave it on Workspace default to use your workspace's standard role for new members.
  6. Optionally change Patients per run (default 100, maximum 500). Any extra patients are picked up on the next sync.
  7. Click Save.

Discovery runs as part of the connection's member sync, which runs automatically every 6 hours by default; click Sync Now on the connection's Logs tab when you want to pick up new patients sooner. Each run's outcomes appear on the connection's Logs tab: a created member shows as synced; patients whose department or status doesn't match are skipped with "not admitted by patient discovery settings". If a patient can't be created because of a temporary problem, it shows as failed and the next syncs try it again until it succeeds — an interrupted sync picks up where it left off and never skips patients. Patients that can never be created automatically (for example, one already linked to another member, or when no member role is available) show as skipped with "patient discovery did not create a Member". A patient that keeps failing needs your attention: athena only keeps its change history for a limited time. If you change the departments, a sync already in progress finishes reading the departments it started with, but only departments that are still selected can create new members.

What discovery does and doesn't do:

  • It creates members without login accounts, and it never links a patient to an existing member just because an email or phone number matches. If another member already uses that email or phone, the new member is created without it.
  • It does not give anyone consent to be contacted — your existing outreach and contact settings still decide who is reached and how.
  • It only sees patients that change after it is switched on. Link the patients you already have one at a time, as described above.
  • If you unlink a discovered member, that patient is not re-created.
  • To stop it, switch Enable discovery off and click Save. Existing members and links stay as they are.
  • While discovery is on, preview ("test") sync runs — a dry run or a run limited to a few records — are refused, because a discovery run always reads and advances athena's change feed. Switch discovery off to run a preview.

Once a discovered member exists, your workflows can use their status and department (through your connection's sync rules) to start a journey, and the update patient action can fill in the details gathered during outreach.

Using the API or CLI instead? The card edits the connection's vendorConfig.patientDiscovery settings. You can send the same block with the FHIR connection update command, for example:

yarn gr fhir-connections update -w <workspace-uuid> --id <connection-id> --data '{
  "vendorConfig": {
    "patientDiscovery": {
      "enabled": true,
      "departmentIds": [1],
      "acceptedStatuses": ["<your prospective status>"],
      "maxPatientsPerRun": 100
    }
  }
}'

Add --env / --allow-write as your environment requires. Only the discovery block changes; other connection settings are kept. Send "enabled": false to switch it off.

Why identifier and not name? athenahealth intentionally does not allow apps to run open-ended, practice-wide patient searches (for example, "find everyone named Smith"). Gravity Rail uses the patient's identifier to make the link, which is both the supported path and a stronger privacy guarantee.

Step 4: Give a workflow access to athenahealth actions​

With members linked, connect the athenahealth capabilities to the workflows that should use them.

  • Chart reads in conversation. Attach the EHR tools to a workflow's abilities so an agent can reference a linked member's demographics and recent encounters while it talks with them. See Custom Toolkits for how to attach connection tools to a workflow or agent.
  • Appointments, eligibility, and chart write-back. These run as automated actions — for example, booking a slot the patient chose during a scheduling conversation, or filing a phone-message note after an outreach call. Your Gravity Rail representative can help you wire these into the right workflows.

Each action always targets the patient linked to the member in that conversation — never a patient supplied by the agent or the caller.

What Agents Can and Cannot See​

This integration is built so that AI agents see the minimum necessary information, in keeping with HIPAA principles:

Agents can:

  • Read the chart of the one patient linked to the member they're currently helping.
  • Take scheduling, eligibility, and documentation actions for that same linked patient.

Agents cannot:

  • Search for patients by name or browse your patient list. There is no free-text patient lookup for agents — a privacy protection, and one that athenahealth's platform enforces as well.
  • Access any patient a member isn't explicitly linked to.
  • Silently change clinical data. Notes written back appear as documents in your providers' normal athenaOne review queues, not as invisible edits to the chart.

Every time an agent reads or writes patient data, Gravity Rail records an audit event, and patient information is never written to logs.

Confirm the Result​

  1. Check the connection status. On the FHIR Connections list (or the App Connections → Active tab under Healthcare Connections), confirm your athenahealth connection shows as connected.
  2. Verify a link. Open the connection's Members area and confirm at least one member is linked to a patient.
  3. Test in a conversation. In a workflow that has the EHR tools attached, have a conversation as (or on behalf of) a linked member and confirm the agent can reference that member's chart details and take the actions you configured.

If something isn't working, confirm the connection is enabled, the member is linked to a patient, and the workflow actually has the athenahealth tools attached. Your Gravity Rail representative can help diagnose credential or practice-access issues.

What's Next​

  • Build a scheduling workflow. Combine athenahealth booking with a conversational flow. See Workflows and Journeys for the build steps.
  • Collect intake details conversationally. Pair the chart connection with a Patient Enrollment workflow to gather missing demographics and insurance information before a visit.
  • Manage the connection over time. See App Connections for renaming, disabling, and troubleshooting connections.