> ## 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 Create Claim

> Which posts new charge lines to an existing AdvancedMD visit — the action that generates an insurance claim.

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](/docs/tools/advancedmd-find-patient) 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](/docs/tools/advancedmd-unapply-payment#provider-profile--facility-preservation)).

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

```json theme={null}
{
  "success": true,
  "posted": true,
  "dry_run": false,
  "patient_id": "pat11144215",
  "visit_id": "9680632",
  "episode_id": "11089480",
  "created_charge_ids": ["charge555001", "charge555002"],
  "charge_count": 2,
  "warnings": []
}
```

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