> ## Documentation Index
> Fetch the complete documentation index at: https://agents.nanonets.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 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`:

```json theme={null}
{
  "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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.