Skip to main content
This document covers advancedmd_create_claim, which posts new charge lines to an existing AdvancedMD visit — the action that generates an insurance claim.

​
Authentication

AdvancedMD tools use the existing AdvancedMD connector (office_code, username, password). See advancedmd-find-patient.md for details.

​
What it does

In AdvancedMD a claim is a visit with charge lines. This tool posts new charges to an existing visit via the updvisitwithnewcharges API, which is what produces the claim. The flow:
  1. Resolve codes → FIDs. Raw CPT/HCPCS, ICD-10, and modifier codes are resolved to AdvancedMD master-file FIDs via lookupproccode / lookupdiagcode (codeset 10) / lookupmodcode. Already-resolved FIDs (pcode… / dcode… / mcode…) pass through untouched.
  2. Fetch episode context. getepisodes supplies the responsible party, insurance order, referral plan, and financial class needed on the charges.
  3. Post the charges onto the supplied visit.
It requires an existing visit_id — it does not create or look up the visit.

​
Provider profile & facility preservation

updvisitwithnewcharges rewrites the visit record, and the billing provider and facility are @profile/@facility on the visit element — so a post that omits them clears them (the same bug that reset 58 charges via the balance move; see AdvancedMD Unapply Payment). The tool now resolves the visit’s provider/facility in this order: explicit profile_id / facility → resolved from provider_code → the visit’s current values, read from one of its existing charges. A facility can legitimately be empty, so each value is tracked as known — supplied by the caller, or read from the visit — rather than merely non-empty. An empty-but-read facility is faithful; an unknown one would be cleared. The guard and the payload use the same resolved values, so they cannot disagree.
  • Visit readable (it has at least one charge and AdvancedMD returns the nested shape, which carries a visit record) → both values are known and echoed faithfully, an empty facility included. Only a visit with no provider at all blocks the post.
  • Visit not readable (no charges yet, the read failed, or AdvancedMD returned the flat shape, which carries no visit record) → only what the caller supplied is known, so both profile_id and facility must be supplied; otherwise posting would clear whichever is unknown. Whitespace does not count as supplied.
A blocked post is refused on a real run; a dry run still previews and adds the same message as a warning. After a successful post the visit is re-read and any changed provider/facility is reported as a warning naming the before/after values.

​
Inputs

Required:
  • patient_id: AdvancedMD patient id (pat-prefixed or numeric).
  • visit_id: existing visit id to attach charges to (vst-prefixed or numeric).
  • date_of_service: ISO-8601 (YYYY-MM-DD); the default begin/end/aging date for every charge.
  • charges: at least one charge line.
Optional:
  • dry_run: defaults to false (charges are posted). Set true to resolve codes + episode context and return the exact payload without writing. (Dry run still performs the read-only code/episode lookups, so it validates that codes exist — it needs valid credentials.)
  • profile_id: AdvancedMD location/office profile id for the visit; tenant-specific.
  • facility: AdvancedMD facility FID; tenant-specific.

​
Charge fields

Each charge requires cpt_code. All others are optional:
  • diagnosis_codes (array), modifiers (array) — raw codes or FIDs.
  • pos, tos, units (default 1).
  • Money (strings, to preserve exact amounts): fee, allowed, patient_portion, insurance_portion, patient_balance, insurance_balance, net_fee, debit_adjustment. Sent as supplied (the tool does not compute the split).
  • begin_date, end_date (MM/DD/YYYY) — default to date_of_service.
  • responsible_party, financial_class_code — override the episode-derived values.
  • bill_insurance — defaults to true.

​
Output

warnings flags any diagnosis/modifier that could not be resolved to a FID (it is sent as-is). A cpt_code that cannot be resolved is a hard error — the claim is not posted.

​
Agent Instruction Guidance

This posts real billing charges. There is no idempotency — calling it twice posts duplicate charges. Run with dry_run=true first, review the resolved FIDs and the money split in the payload, then call again without dry_run only after confirmation.
Typical flow: find the patient (advancedmd_find_patient), confirm the visit (advancedmd_find_charge / advancedmd_get_visit_summary), then post the claim with advancedmd_create_claim.