Skip to main content
This document covers athenahealth_get_patient, the AthenaHealth patient-lookup tool exposed through the Agents Platform.

​
Authentication and enablement

Uses the existing AthenaHealth connector credentials (client_id, client_secret, practice_id, environment). The tool does not accept raw access tokens. It is off by default — enable it on the agent.

​
athenahealth_get_patient

Fetches one patient and every insurance plan on file for them, by AthenaHealth patient ID. This is read-only and makes two GETs: /patients/{id} and /patients/{id}/insurances. Use it when you hold a patient ID and need demographics, coverage, or both. When you hold an encounter/visit ID instead, use athenahealth_get_encounter_summary: it resolves the patient itself and also returns the appointment and nearby appointments.

​
Inputs

Required:
  • patient_id: AthenaHealth patient ID. A value that a variable resolved to a float (946977.0) is normalized to 946977; a non-numeric value fails locally before the call.

​
Output

structuredContent:
patient is the AthenaHealth record, unwrapped from the single-element array the API returns, so a downstream step can read ${VAR_N}.patient.dob. insurances is the plan list in AthenaHealth’s own sequence order (1 = primary, 2 = secondary), so ${VAR_N}.insurances[0].insuranceidnumber is the primary member ID. Both carry every field the practice populates — the examples above are abridged. insurances is always a list, never null: a patient with no coverage on file returns []. Common failure reasons:
  • athenahealth_not_connected — no active AthenaHealth integration for the workspace.
  • patient_id is required / patient_id must be a positive integer — rejected before any API call.
  • AthenaHealth API error (for example HTTP 404 for an unknown patient ID).
A failed insurance lookup does not fail the call: the demographics still return, insurances is [], and errors.insurances carries the AthenaHealth message. Check that key before reading coverage as “none on file”.

​
Limits and side effects

Two GETs per call, no writes. The tool returns a single patient; it does not search by name, DOB, or MRN. Cancelled plans are not requested.

​
Human-readable text

The tool emits two markdown sections for the feed. ## Patient is a field table: call status, practice ID, name, patient ID, DOB, sex, patient status, marital status, address, home phone, email, department ID, and registration date. ## Insurance (N) is one row per plan: sequence, payer, plan, member ID, type, eligibility status, last checked, policy holder, phone, and relationship to insured. It is omitted when the patient has no plans. Both are the same tables the encounter summary renders.

​
Agent instruction guidance

Call it when a trigger or a prior step gives you a patient ID and the next decision needs demographics or coverage — an eligibility check, a chart-alert call that needs the primary department ID, or a patient-matching step. One call answers “who is this patient and what are they insured under”, so do not follow it with an encounter lookup just to read the insurance.