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.
  • 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.

  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.

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 Appointment Reminder and Voice Call Assistant for patterns you can adapt.
  • Collect intake details conversationally. Pair the chart connection with a Patient Intake 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.