AthenaHealth Get Patient

AthenaHealth patient and insurance lookup by patient ID, exposed through the Agents Platform.

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:

{
  "success": true,
  "practice_id": "195900",
  "patient_id": "946977",
  "patient": {
    "patientid": "946977",
    "firstname": "Jane",
    "lastname": "Doe",
    "dob": "01/02/1980",
    "sex": "F",
    "primarydepartmentid": "99"
  },
  "insurances": [
    {
      "sequencenumber": "1",
      "insurancepayername": "CIGNA",
      "insuranceplandisplayname": "CIGNA HMO",
      "insuranceidnumber": "1232456",
      "insurancetype": "Commercial",
      "eligibilitystatus": "Eligible",
      "eligibilitylastchecked": "09/01/2026",
      "insurancepolicyholder": "DOE, JANE",
      "relationshiptoinsured": "Self"
    }
  ]
}

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.

A failed patient read carries a reason and a retryable flag in structuredContent, and both are still IsError results:

reason	retryable	Meaning
patient_not_found	no	AthenaHealth answered HTTP 404: there is no patient with this ID.
lookup_failed	yes	Any other failure — a 5xx, a timeout, a rejected request. The patient may well exist; AthenaHealth could not be asked. The original AthenaHealth error text is kept as the message.

Keep the two apart. An agent that looks one bare ID up in more than one EHR may move on to the next system after patient_not_found, but must not after lookup_failed: AthenaHealth and DrChrono reuse the same numbers for different people, so treating an outage as a miss can match the ID to a different patient elsewhere.

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.