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 — including finding times and booking in the conversation.
  • Record insurance and check coverage for a patient.
  • 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").
  • Your practice must authorize the Gravity Rail app in athenahealth. You do not create an app or copy a client ID or secret: Gravity Rail operates one athenahealth app, and your practice's athenahealth administrator enables it for your practice. Your Gravity Rail representative coordinates this with you and enables the practice for your organization in Gravity Rail.
  • 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 athenahealth​

  1. In the left sidebar, open App Connections.
  2. Choose athenahealth.
    • 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.

Step 2: Enter your practice ID and connect​

On the Setup tab:

  1. Practice ID — enter your athenahealth practice (Context) ID. It is a number.
  2. Environment — choose Preview (athenahealth's sandbox) or Production (your live practice). An environment Gravity Rail cannot reach yet is shown but cannot be chosen. Production is enabled once athenahealth issues Gravity Rail production credentials.
  3. Click Verify access. Gravity Rail asks athenahealth for access and reads one item of practice setup. Nothing is saved yet. If verification fails, the message tells you what to fix:
    • This practice has not authorized the Gravity Rail app — ask your athenahealth administrator to enable Gravity Rail for the practice, then verify again.
    • athenahealth has no practice with this ID — check the ID, or choose the other environment.
    • athenahealth is limiting requests or did not respond — wait a minute and try again.
    • The hourly limit for access checks is reached — each person can verify 20 times an hour, and a workspace 60 times. Try again later.
    • Verification is temporarily unavailable — try again in a few minutes.
    • Gravity Rail has not enabled this practice for your organization — contact Gravity Rail support: your representative confirms the practice is yours, then enables it.
    • Another Gravity Rail workspace already connects this practice — a practice connects to one workspace in each environment. Contact Gravity Rail support to move it to this workspace.
  4. Click Connect athenahealth. The button turns on after a successful verification of the same practice ID and environment.

The connection then shows its status in the header on every tab. The page has the same tabs as every supported integration: Overview, Members, Settings (what to sync), Sync (Sync now and run history), Data (where the connection keeps its data) and Setup (connection name, practice, environment and authorization details). Overview shows sync success rate and Member counts. Its Unlinkable count always shows 0: athenahealth matches by an already linked patient record or by name and date of birth, and the count does not inspect either. When patient records fail to sync, Sync issues below the counts lists each cause in plain words, how many records it affects and what to do; select the Errored count to go there. The Data tab is read-only: it shows which Data Types the connection keeps its patient data in, each dataset's state, and how many of those records you can see. The Sync tab's Preview one Member's write shows what would be written to one Member's linked patient, without sending anything; it sits beside Preview Sync, the dry run of the whole connection. For what the Data tab's states mean and when the write preview is shown, see Seeing Where a Connection Keeps Its Data and Write Preview for One Member.

On Settings, Conflict policy decides what Member inbound rules do when a Gravity Rail field already has a value: Remote wins (the default) replaces it with the athenahealth value, and Keep local writes only where no value is set. Outbound writes are not affected. If saving settings shows Sync settings were not saved, see When a Save Is Refused.

Open the header's three-dot menu for Test connection or Disconnect; disconnecting asks for confirmation. To connect another practice, use Add practice. To change the environment, connect the practice again in the other environment.


Gravity Rail only reads or writes a patient's chart once you've explicitly linked that Gravity Rail member to their athenahealth patient record. By default Gravity Rail never matches automatically: every link names one exact patient record — one at a time from the Members tab, through optional patient discovery, or through an import by department and status (both below). If you switch on matching by name and date of birth (below), exact matches can also link automatically.

  1. Open the athenahealth page and go to the Members tab.
  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. By default Gravity Rail never matches by name or date of birth, so there's no risk of accidentally attaching the wrong chart.

Optional: match by name and date of birth​

If you set the connection's Member match strategy to Match by Name + Date of Birth, Gravity Rail can also link a member to a patient whose first name, last name and date of birth are exactly the same (ignoring case, accents, punctuation and middle names). It never matches by email, and it never links when more than one member or patient fits, or when the member is already linked to another patient — those wait for you on the Members tab. A phone number only decides between several members who match; it never stops a single match.

It is off until you turn it on. Before you do, know the risk: two different people can share a first name, last name and date of birth. A wrong match links the wrong patient to a member. That patient's details then sync into the member, and if you also use outbound sync, conversation logging or athenahealth actions such as booking, the wrong patient's chart is written to.

Two places use it:

  • Linking unlinked members in bulk: on request, Gravity Rail looks up every unlinked member in athenahealth once and links the exact matches. There is no in-app button for this yet; ask your Gravity Rail contact to start a run.
  • Patient discovery (below): a changed patient that matches an existing member links to that member instead of creating a new one.

Optional: import patients by department and status​

A workspace administrator can bring in the patients of chosen departments who have chosen patient statuses (active, inactive or prospective). Each patient becomes a Gravity Rail member linked to that exact patient record; a patient who is already linked, or whom you unlinked by hand, is skipped.

The Import Members dialog does not appear on the athenahealth page yet; it is coming. Today an administrator runs the import through the API (workspace:admin):

  1. Preview the selection: POST /api/v2/w/{workspace}/app-connections/{connection_id}/subset-imports/preview with {"selection": {"kind": "field_filter", "params": {"departmentIds": [1], "statuses": ["prospective"]}}}. The response shows athenahealth's count and the first few patients. Nothing is created.
  2. Save it: POST …/subset-imports with a label and the same selection.
  3. Run it: POST …/subset-imports/{import_id}/run. Follow progress with GET …/subset-imports/runs.

Limits set by athenahealth's terms: at most 5 departments; patients are read only between 9 p.m. and 8 a.m. Eastern (a run started during the day waits for the evening); one run reads at most 50 pages of 100 patients and then stops; run it again to continue where it stopped. Imports by appointment date or from a file of patient IDs are not available until athenahealth approves them.

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 Settings tab;
  • 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 athenahealth page's Sync tab when you want to pick up new patients sooner. Each run's outcomes appear on the Sync 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, or — with matching by name and date of birth on — in bulk.
  • 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.

Optional: let the agent schedule in the conversation​

Add the athenahealth Scheduling ability to a workflow (or a task) so the agent can, for the patient it is talking to:

  • find open appointment times for your department, new-patient reason and providers;
  • record the patient's insurance — the agent reads the matching plans to the patient and records only the one they confirm;
  • check insurance coverage for today; and
  • book a time the patient chose — only when Book appointments is on.

You need permission to manage app connections to save it. The settings:

SettingWhat to enter
athenahealth connectionAn enabled athenahealth connection in this workspace.
Department IDThe athenaOne department the appointments belong to.
New-patient reason IDA new-patient scheduling reason from your practice (the "any reason" wildcard is not accepted).
Provider IDs1–20 athenaOne provider IDs, separated by commas.
Days ahead to search1–14 (default 7).
Require confirmed coverageOff by default. Turning it on adds a coverage requirement; it never removes one your connection already has.
Activate patient when bookingOff by default. When on, the patient's athenahealth status is set to active just before their appointment is booked; when off, a new (prospective) patient is booked as they are.
Book appointmentsOff by default. When off, the agent can find times and handle insurance but has no booking tool.

Coverage. Your representative can set a practice-wide rule on the connection that coverage must be confirmed before any booking, and how recent that confirmation must be (7 days unless changed). Coverage results are stored on the patient's athenahealth Patient Outreach State record as covered, not covered, unknown, pending or no insurance. Until your practice and Gravity Rail agree which athenahealth eligibility answers mean "covered", every check is recorded as unknown — so a practice that requires coverage will see bookings refused and handed to staff. That is intended: the agent never promises coverage it was not told about. A journey can route on this value: covered to scheduling, no insurance to insurance capture, not covered to staff, and anything else (including no check yet) to a retry and then staff.

Automated booking rules. A booking action in an event rule books the open slot it names, for the linked patient, following the same coverage rule. An eligibility action may leave out the insurance record ID: Gravity Rail then checks the patient's primary insurance. An existing rule that names a specific insurance record keeps working as long as that record is still on the patient.

When a booking can't be confirmed. If athenahealth doesn't clearly answer whether a booking succeeded (for example, a timeout), Gravity Rail does not retry and does not tell the patient it is booked. The patient's outreach state stays pending, which blocks a second booking, until someone reconciles it (next section). A booking that athenahealth confirmed but Gravity Rail could not record shows as recording failed and also needs reconciling.

What Gravity Rail watches for you. Each sync re-reads a booked appointment from athenahealth: a cancellation there releases the patient for a new booking, and a reschedule is followed. A booking attempt left pending or recording failed for more than 30 minutes raises an internal alert to the Gravity Rail on-call team, who will reach out; you can also see it on the outreach state record at any time. Attempts on a disabled connection are not watched.


Reconciling an uncertain booking​

A workspace admin resolves a pending or recording failed booking attempt through the API, after checking athenahealth. First open the patient's athenahealth Patient Outreach State record and note the Booking attempt ID, Booking attempt slot (date, time, provider and department), Booking attempt appointment ID (the athenahealth slot the attempt tried to book), Booking attempt phase and Booking attempt worker.

POST /api/v2/w/{workspace_uuid}/app-connections/fhir/connections/{connection_id}/members/{member_id}/outreach-state/reconcile

If the appointment exists in athenahealth (for this patient, at exactly the attempt's date, time, provider and department, under the attempt's Booking attempt appointment ID), record it:

{
"attemptId": "3f6a0c3e-1b7e-4c1e-9a51-0f2d4b8c9e10",
"appointmentId": "900",
"vendorOutcomeConfirmed": true
}

Gravity Rail records only the attempt's own appointment ID (any other ID is refused with attempt_appointment_mismatch, even one at the same time), and only after reading it from athenahealth shows it belongs to this patient and matches the attempt's slot exactly; an appointment for the same patient at a different time is refused.

If no appointment exists, clear the attempt so the patient can book again:

{
"attemptId": "3f6a0c3e-1b7e-4c1e-9a51-0f2d4b8c9e10",
"clear": true,
"vendorOutcomeConfirmed": true,
"executionTerminated": true
}

What you must confirm depends on the attempt's phase:

PhaseTo clear
ClaimedNothing — no request had been sent.
Vendor call returned, or state recording failedvendorOutcomeConfirmed: you checked athenahealth and there is no such appointment.
Vendor call startedBoth vendorOutcomeConfirmed and executionTerminated: you confirmed the worker named in Booking attempt worker has been stopped and cannot resume.

An attempt with no phase is refused — investigate it instead. Age alone never makes an attempt safe to clear. The response returns only IDs and the result ("bookingState": "booked" or "none"); refusals return a fixed code such as execution_termination_required or appointment_not_verified. Every reconciliation is recorded in the audit log as a booking reconciled event (ehrBookingReconciled) with your identity and what you confirmed.

Changing the patient link. While a booking attempt is pending or recording failed, Gravity Rail refuses to change or remove that Member's athenahealth link (booking_attempt_unfinished): the attempt is recorded against the patient it was made for. Reconcile the attempt first, then change the link. If the link was changed anyway, reconciling returns attempt_identity_mismatch and no further booking runs for that attempt: link the Member back to the original patient, reconcile the attempt, then change the link.


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 App Connections → athenahealth, the header shows the connection as Connected on every tab.
  2. Verify a link. Open the Members tab 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.