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

# AdvancedMD Find Charge

> Native AdvancedMD charge lookup tool exposed through the Agents Platform.

This document covers `advancedmd_find_charge`, the native AdvancedMD charge lookup tool exposed through the Agents Platform.

## Authentication

AdvancedMD tools use the existing AdvancedMD connector. Users configure:

* `office_code`
* `username`
* `password`

The connector performs AdvancedMD's two-step API login, discovers the tenant API base URL, caches the security token, and refreshes it when needed. Tools do not accept `amd_token` and do not require callers to provide a direct `processrequest.aspx` URL.

## `advancedmd_find_charge`

Finds an AdvancedMD charge by patient name, date of service, and CPT code. This is a read-only lookup tool intended to retrieve charge IDs, balances, portions, provider details, and responsible-party details.

### Voided and settled charges

The transaction-history scan always requests the **full** history (`@typefilter=0`): AMD's server-side filter also hides settled charges, which made freshly posted charges report "not found" on re-reads. Voided charges are filtered client-side instead, controlled by `include_voided_charges`.

Matching **prefers a live charge**: a voided row can never shadow a live replacement for the same DOS + CPT (the void-then-re-enter case). With `include_voided_charges=true`, a voided charge is returned only when no live match exists anywhere in the scanned pages, and it is flagged — `match_is_voided: true` in the structured output and a `⚠️ VOIDED` row in the summary saying not to post to it.

## Inputs

`date_of_service` accepts `YYYY-MM-DD`, `MM/DD/YYYY` and `M/D/YYYY`. EOB documents and AdvancedMD both print `MM/DD/YYYY`, and rejecting it caused two production tasks to fail outright on 2026-08-03 after four identical retries each.

Required:

* `patient_name`: Patient name in a common format, such as `Jane Smith` or `Smith, Jane`.
* `date_of_service`: ISO-8601 date, `YYYY-MM-DD`. The tool converts this to AdvancedMD's `MM/DD/YYYY` format internally.
* `cpt_code`: CPT code to match. Modifiers are allowed; matching uses the base CPT, so `99213 25` matches `99213`.

Optional:

* `exact_match`: Defaults to `true`. Controls AdvancedMD patient-name lookup exact matching.
* `max_patients`: Defaults to `10`. Maximum patient candidates to inspect.
* `max_transaction_pages`: Defaults to `10`. Maximum transaction-history pages to inspect per patient.
* `include_voided_charges`: Defaults to `false`. When false, only active/non-voided charges are searched. Set to true only when the workflow intentionally needs to inspect voided charges.

### Matching Behavior

The tool:

* generates common patient-name variations before lookup,
* deduplicates patients by AdvancedMD patient ID,
* strips a leading `pat` prefix before calling transaction history,
* pages through `gettxhistory`,
* matches by date of service and base CPT code,
* skips charges flagged as voided (`void != "0"`) unless `include_voided_charges=true` — AdvancedMD's server-side type filter alone does not reliably exclude voided charge rows, so they are filtered here too,
* calls charge detail (`getchargedetaildataicd10`) to enrich insurance/patient portions and balances. Both response shapes AdvancedMD uses are handled — a flat `<charge>` under `Results` and the nested `patientlist > patient > visitlist > visit > chargelist > charge` envelope production tenants return. Transaction-history values are the fallback when the detail read has no value.

### Output

On success, structured content includes:

* `found: true`
* `patient`: matched AdvancedMD patient attributes
* `match`: EHR details such as charge ID, patient ID, visit ID, balances, portions, provider, carrier, and raw transaction fields
* `match.ehr_carrier` / `match.ehr_carrier_name`: the carrier **currently attached to the charge** (the payer the charge is assigned to for billing) from the `gettxhistory` charge row — not the patient's full insurance list, and distinct from the row's `lastbilledcarrier` (available in `raw_transaction`). `ehr_carrier` is the code (e.g. `AET07`); `ehr_carrier_name` is its display name resolved via `lookupcarrier` (best-effort — empty if the lookup fails). A charge row carries exactly one carrier; when a claim crosses over, this value changes to the now-responsible carrier. For the patient's full primary/secondary list with names, use `advancedmd_get_patient_insurances`.
* `patient_insurances` (top-level, best-effort): the matched patient's insurance plans on file from `getdemographic` — per plan: resolved carrier name (`Carrier`), raw AMD carrier code (`CarrierCode`), `Active` (raw AMD flag; `"0"` = inactive), `Coverage` (Primary/Secondary/…; AMD's `0` maps to `Unassigned`), `SubscriberNum`, `GrpNum`, begin/end dates, relationship. Same shape as `advancedmd_get_patient_insurances`. Omitted when the lookup fails or the patient has no plans on file. The summary table renders one `Insurance (Primary)` / `Insurance (Secondary)` row per plan, hiding explicitly-inactive plans (the structured list keeps them all).
* `match.applied_payments`: the payments already applied to the matched charge, from the charge's nested `paymentlist` in `gettxhistory`. Each entry carries `payment_id` (the ID [AdvancedMD Unapply Payment](/docs/tools/advancedmd-unapply-payment) takes), `date`, `amount`, `check_number`, `pay_code`, `source`, `void`, `pay_reason_code`, and the raw payment attributes. Check `void` before acting on a payment — voided rows are included. **Sign convention:** AMD reports applied amounts sign-flipped — a \$104.40 payment applied to the charge appears as `amount: "-104.40"` (prod-confirmed). When matching an EOB amount to a payment, compare against the absolute value.
* `match.ehr_carrier_id` / `match.carrier_id`: AdvancedMD's **carrier id** (e.g. `car7552`), resolved from the same `lookupcarrier` call that provides the display name — this is what a payment's `@carrierid` takes, and passing it to [AdvancedMD Post Payment](/docs/tools/advancedmd-post-payment) saves that tool a lookup. `carrier_id` holds the same id once resolved (it previously carried the display code, the naming confusion behind the June regression) and falls back to the code when the lookup finds nothing. The display code itself stays in `ehr_carrier`.
* `match.applied_payments_reconciled`: whether the listed non-voided payments account for the charge's paid amount (within a cent, using the sign convention above). AMD often nests only part of a charge's payments under the row a scan finds first (typically just adjustments); when the matched row doesn't reconcile, the tool **sweeps the remaining history pages** and merges the same charge's payments from its other transaction rows. If the list still doesn't reconcile after the sweep, this flag is `false` and the summary adds a `⚠️ Payments Incomplete` row — the agent must not pick an unapply target from an incomplete list; verify in AdvancedMD instead. The sweep only runs when needed, so charges whose first row already reconciles (including unpaid charges) cost no extra API calls.

Example shape:

```json theme={null}
{
  "found": true,
  "patient": {
    "id": "pat123",
    "name": "SMITH, JANE"
  },
  "match": {
    "ehr_charge_id": "456",
    "ehr_patient_id": "123",
    "date_of_service": "05/01/2026",
    "ehr_cpt_code": "99213",
    "ehr_insurance_portion": "70.00",
    "ehr_patient_portion": "30.00",
    "ehr_carrier": "AET07",
    "ehr_carrier_name": "AETNA HEALTH PLANS",
    "patient_id": "123",
    "charge_id": "456",
    "carrier_id": "789",
    "provider_code": "DOC1",
    "applied_payments": [
      {
        "payment_id": "401286",
        "date": "07/09/2026",
        "amount": "-1.08",
        "check_number": "601601250977",
        "pay_code": "PI",
        "source": "2",
        "void": "0",
        "pay_reason_code": "CO45"
      }
    ]
  }
}
```

The markdown summary adds an "Applied Payments" row when payments exist, e.g. `id 401286: -1.08 (chk 601601250977, PI)`.

Common failure reasons:

* `patient_not_found`: no AdvancedMD patient matched the supplied name variations.
* `charge_not_found`: patients were found, but no transaction matched the date of service and CPT code.
* `advancedmd_not_connected`: AdvancedMD is not connected. The agent should ask the user to either connect AdvancedMD and try again, or stop the task.

### Candidates on `charge_not_found`

An EOB date of service that disagrees with AdvancedMD's is the top cause of false "charge not found" (production tasks escalated lines a human then matched by eye). When the patient matched but no charge hit the exact DOS + CPT, the response includes the same-CPT charges seen on **other** dates:

* `candidate_charges`: up to 5 candidates across the scanned pages of **all** matched patients, nearest the requested DOS first — each with `ehr_charge_id`, `ehr_patient_id`, `ehr_visit_id`, `date_of_service`, `ehr_cpt_code`, `ehr_charge_amount`, `ehr_paid_amount`, `ehr_provider_code`, `ehr_carrier`, and `voided`. Voided charges appear only with `include_voided_charges=true` and are flagged.
* `message`: tells the agent to verify the EOB DOS against the candidates before escalating the line.

The summary table adds one `Candidate <CPT>` row per candidate. The `reason` stays `charge_not_found` — a candidate is a lead to verify (typically by re-running the lookup with the candidate's DOS), never an automatic match.

## Agent Instruction Guidance

When using `advancedmd_find_charge` in an agent workflow, explicitly state whether voided charges should be included.

Recommended default for EOB charge-matching workflows:

```text theme={null}
For each EOB line item, call AdvancedMD: Find charge with:
- patient_name from the EOB line item
- date_of_service in YYYY-MM-DD format
- cpt_code from the EOB line item
- include_voided_charges = false, so AdvancedMD only searches active/non-voided charges
```

Use `include_voided_charges = true` only when the workflow specifically needs to inspect voided charges.

Example workflow instruction:

```text theme={null}
1. For each EOB line item, match it to the corresponding AdvancedMD charge using AdvancedMD: Find charge.
   - Use patient_name, date_of_service, and cpt_code from the EOB.
   - Set include_voided_charges = false by default to exclude voided charges.
   - If the workflow requires checking voided charges, set include_voided_charges = true and mention that in the review.

2. Generate a charge matching review table with EOB fields and EHR fields from the match result.

3. If the result reason is advancedmd_not_connected, use Ask User with only these options:
   - Connect AdvancedMD and try again
   - Stop task

4. Ask the user for review if a patient or charge cannot be matched confidently.
```