AdvancedMD Find Charge

​

Authentication

• office_code
• username
• password

​

advancedmd_find_charge

​

Voided and settled charges

​

Inputs

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

• 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

• 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

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

{
  "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"
      }
    ]
  }
}

• 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

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

​

Agent Instruction Guidance

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

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.