Encounter, Claim, Line
What an encounter, a claim family, a claim and a service line are; how gold builds each one from athena today; and how the legacy pipeline's "account" differs. Every definition starts from Jacob's Core Concepts doc, and one realistic visit runs through the whole page.
Quotes in italics are from Core Concepts (Jacob), section names given. "Gold" means the medallion silver and gold layers. "Legacy" means the dbt transforms that feed the old MD Clarity database. Two changes in the current draft PR stack are marked where they apply: #6259 (rebill chains) and #6264 (claims and lines take their encounter's masters).
The shape
An appointment can produce one or more encounters. An encounter is one billing party's claim family. The family holds every claim submitted for it, at each payer in turn, and the service lines being billed. The payer answers each claim with a remittance.
The concepts
For each one: what Core Concepts says, what gold builds from athena, and what the legacy pipeline did.
Encounter
encounterCore Concepts
A single billable event: one provider, one date of service (or date range if inpatient), one place of service, one claim type, and the set of procedures performed. It is the foundational unit of work in RevFind.Encounter & Claim Structure
An encounter is scoped to who is billing. … An encounter can span more than one claim (an original plus a corrected rebill, or a primary plus a secondary) but always for the same billing party.Encounter & Claim Structure
Gold
One row per athena claim family in encounter. Its provider, location, TIN, coverage and diagnoses come from one representative claim: the live primary submission, else the original.
An encounter is published only when its location, provider, practice and TIN all resolve to masters that aren't hidden. Every other family lands in excluded_encounter with a reason.
Legacy
Called an account, and it was a different thing: one athena clinical encounter (a visit), with exactly one claim attached. See Legacy account vs encounter.
Claim family
encounterclaimCore Concepts
A single surgery produces separate encounters for the surgeon, the anesthesiologist, and the facility, because each bills its own claim family.Encounter & Claim Structure
The doc uses "claim family" without defining it. In practice it's an original claim plus every claim that corrects or replaces it.
Gold
athena links a rebill to the claim it replaced through originalclaimid. Gold follows that link back to the first claim, the root, and the root's id becomes the family's root_claim_id.
#6259, in review: today gold stops one link short, so a rebill of a rebill opens a second family. Production has one such chain.
Legacy
No family. The appointment points at the original claim only, so rebills are never attached to the account.
Claim
claimCore Concepts
A single submission to a payer: the 837 sent by the provider. A claim belongs to an encounter and carries the identifiers an appeal needs, most importantly the ICN. … One encounter can have several claims over its life.Encounter & Claim Structure
Gold
One row per athena claim per coverage position: primary, secondary, and the patient's own position. An athena claim isn't one 837: the same claim is billed to the primary and then to the secondary, and gold splits those apart.
Positions that were never submitted are kept, because payers sometimes remit against them. is_billed marks real submissions, and is_effective marks the live one at each position. The ICN comes from the payer's remit, once it has answered.
Legacy
One claim id per account, shown in the app as the account's "Claim ID". Rebills, and any other claims on the visit, don't appear.
Service line (claim line)
service lineCore Concepts
A single billed service within an encounter: a procedure or revenue code, its modifiers, units, and amounts. Lines are where downcoding and line-level packaging show up.Encounter & Claim Structure
If a claim requires more than four modifiers for a specific line item, you must use Modifier 99 as the fourth modifier.Codes · Modifier
Gold
One row per non-voided athena charge in service_line. The procedure code is split from its modifiers, and modifier_overflow flags the Modifier 99 case.
For anesthesia, units are replaced with timesheet minutes; the doc's anesthesia units are base units plus time increments. The payer's answer for each line, at each coverage position, is in service_line_adjudication.
Legacy
The charges on the account's one claim, with their payments and adjustments aggregated to the account.
Coverage
claimCore Concepts
A patient's payer on an encounter: which payer and plan, and at what order (primary, secondary, tertiary).Remittance & Money
Gold
encounter_coverage: one row per encounter per position, read from the representative claim's policy slots as of the date of service. athena keeps primary and secondary on the claim, so there is no tertiary.
Legacy
The claim's primary policy decides the account's payer. Secondary data is kept per charge.
Remittance
remittanceCore Concepts
The payer's response to a claim, explaining what they paid and why. … This is where actual reimbursement amounts and the reason codes for any reductions or denials live.Remittance & Money
EDI is the preferred source … PM posted data is the fallback.Expected, Actual & Variance
Gold
Each remit row finds its claim position by matching the policy it paid against, never by date. Answers for a line go to service_line_adjudication, and answers with no line go to claim_adjudication.
Where the remit and the practice's own posting both record a payment, the remit wins (transaction.is_superseded). That matches the doc's EDI-first rule.
Legacy
Only remits for the account's one claim. Remits for a corrected claim aren't attached.
Visit, and the appointment map
Core Concepts
A pre-service scheduled encounter: a single appointment from the scheduling system … distinct from an Encounter in RevFind.Flow (Pre-Service) · Visit
Tying an appointment to the encounters it spawns on the back end. Sometimes is obvious in PM systems, sometimes you have a fuzzy match of Patient + DOS + Location.Appointment Encounter Map
Gold
For athena the map is exact. Each encounter carries source_appointment_id and source_clinical_encounter_id, found through its original claim, and one appointment can map to several encounters. An 835/837 feed would need the fuzzy match, which isn't built yet.
Legacy
The visit was the account. So the legacy "account" is closer to the doc's Visit than to its Encounter, and the rename changes the unit, not just the name.
One visit, end to end
An illustrative case, not real data: a knee injection visit at a pain management practice that bills with athena. The ids are invented, and the codes and reason codes are real.
- Mar 4The visit. Appointment 778899, clinical encounter 554433. The provider sees the patient (an E/M visit), injects the knee and administers triamcinolone. Place of service 11, office.
- Mar 5Original claim 81234 goes to the primary payer, Anthem PPO:
99214,20610, andJ3301× 4 units (40 mg). The E/M line is missing modifier 25. - Mar 19Anthem's 835 (ICN 2026078301144) pays 20610 and J3301, and denies 99214 with CARC 97: benefit included in the payment for another service.
- Mar 24Corrected claim 81260 (frequency 7, replacement) adds modifier 25 to 99214. athena records
originalclaimid = 81234. - Apr 8Anthem's 835 on the correction (ICN 2026098300517) allows all three lines.
- Apr 1081260 goes to the secondary payer, Medicaid, for the patient's remaining share.
What gold builds
One encounter: the family rooted at 81234. Its attributes come from 81260, the live primary submission.
| claim (athena) | position | billed | effective | parent | frequency | ICN |
|---|---|---|---|---|---|---|
| 81234 | primary | yes | no | — | original | 2026078301144 |
| 81234 | patient | no | no | — | original | — |
| 81260 | primary | yes | yes | 81234 · primary | 7 (replacement) | 2026098300517 |
| 81260 | secondary | yes | yes | 81234 · secondary | 7 (replacement) | from Medicaid's remit |
| 81260 | patient | no | yes | 81234 · patient | 7 (replacement) | — |
claim: five rows from two athena claims. Grey rows are superseded by the correction.
| service line | procedure | modifiers | units | charged | answered at |
|---|---|---|---|---|---|
| line 1 | 99214 | 25 | 1 | $210.00 | primary (denied, then allowed), secondary |
| line 2 | 20610 | — | 1 | $185.00 | primary, secondary |
| line 3 | J3301 | — | 4 | $40.00 | primary, secondary |
service_line: three lines on the encounter. service_line_adjudication holds each line's current answer at each position.
The payment variance is computed for the encounter against its primary coverage, once the payer has answered. The March denial of 99214 stays in the transaction history, but the April answer is the line's current one.
What legacy builds
| legacy account | claim attached | counts | doesn't count |
|---|---|---|---|
| 554433 | 81234 | The original claim, its charges, and Anthem's March remit with the 99214 denial | Anything recorded against 81260: the corrected claim, Anthem's April allowance of 99214, and the Medicaid secondary |
On this visit, legacy shows 99214 as denied even after the correction was paid, because the payment was recorded against claim 81260. Gold shows it as allowed. This is the most common reason legacy and gold totals won't tie out for a rebilled visit.
Who bills: one procedure, several encounters
Core Concepts' surgery example, applied to a fluoroscopy-guided spinal injection at an ambulatory surgery center:
| Billing party | Claim form | Claim type | Encounter | In this customer's athena data? |
|---|---|---|---|---|
| The pain physician's practice | CMS-1500 (837P) | Professional | Its own claim family | Yes, if the practice bills in athena |
| The anesthesia group | CMS-1500 (837P) | Professional | Its own claim family | Only if the same customer bills anesthesia |
| The ASC | UB-04 (837I) | Facility | Its own claim family | Only if the ASC is the customer's own TIN |
Gold sees only what the customer bills, so a practice customer usually has just the first row. A family's billing party is whatever athena recorded on its claims, and that isn't always one party; see the next section.
Legacy account vs encounter
| Legacy account | Gold encounter | |
|---|---|---|
| What it is | A visit: one athena clinical encounter, or a claim with no appointment (<claimid>-CLAIMONLY) | One billing party's claim family |
| Claims included | One: the smallest claim id linked to the visit | Every claim in the family, at every coverage position |
| Rebills | Not attached; their money never reaches an account | In the family, with their money |
| Rebill of a rebill | Not attached | Joins the original's family (#6259) |
| Claim with no appointment | An account only if it's an original | Its own family, rebills included |
| Two original claims on one visit | One is kept, and the other's money is dropped | Two encounters that share a legacy_account_id |
| Where attributes come from | The visit, then the one claim | The live primary submission, else the original |
| A visit with no claim | Still an account, with no charges | No encounter until something is billed |
Bridging the two. encounter.legacy_account_id reproduces legacy's mapping for each family, through the original claim's appointment or the claim-only rule. It's many encounters to one account, and some encounters have none. Use it to find a legacy account, not to reconcile totals row for row.
Where this is defined: legacy in models/legacy/transform/transform_account_grain.sql (every money model joins on its single claim_id); gold in stg_claim_family, encounter and src_encounter_reference.
Gold vs Core Concepts
Where gold, the data layer, doesn't yet hold to the doc's definitions. Phoenix's gaps are in the appendix.
| Core Concepts | Gold today | Status |
|---|---|---|
| An encounter has one billing party | athena sometimes records a different pay-to TIN on a secondary claim: 2,229 production claims differ from their encounter | #6264 gives every claim and line its encounter's TIN, provider and location |
| One date of service | The service dates span every charge in the family, including charges on replaced claims, so a professional encounter can show a range | Open |
| One place of service | The encounter takes one, but a line keeps its own charge's | Open |
| A claim is one 837 submission | A claim is an athena claim at one coverage position, including positions never submitted | Open; the 835/837 feed will need a decision |
| Primary, secondary, tertiary | No tertiary in athena's claim slots | Source limit |
| Anesthesia units are time increments plus base units | Gold carries minutes; pricing converts them | By design |
| Payer is the operating entity (BCBS OK vs TX); Brand is the family | Gold's payer_id is brand level (Aetna, Anthem, Blue Cross Blue Shield, and so on). There's no operating payer, and no pricing payer for the BlueCard case | Open |
| Financial class, network product, plan | lob is close to financial class. plan_type (HMO, PPO) and plan_descriptor (athena's package name) mix network product and plan | Open |
| Code category, DRG, ICD-10-PCS | The code system only (CPT, HCPCS, local). The DRG code comes from the remit; the DRG system, severity and ICD-10-PCS columns are null | Source limit for a professional practice |
| Fuzzy appointment-to-encounter match | Exact for athena only | Needed for 835/837 |
Keys, for engineers
| Key | Built from | Notes |
|---|---|---|
| encounter_id | sk(root_claim_id) = md5('athena:' || context || ':' || root) | Stable unless the family's root changes, which is what #6259 does to one production chain |
| claim_id | sk([source_claim_id, cob]) | Five rows in the example, from two athena claims |
| parent_claim_id | The root claim at the same position | Set only on rebills |
| service_line_id | sk(parentchargeid) | The same id space remits use to reach a line |
| legacy_account_id | Clinical encounter id, else <root>-CLAIMONLY | Not unique; may not exist in the legacy database |
athena ids are unique only within one athena account (its "context"), so never join on a bare athena id. Identities the outside world assigns (TIN, NPI, address) use global_key instead and match across sources.
Appendix: gold vs Phoenix
Phoenix reads only gold and keys all of its own records (labels, projects, appeal stages) on encounter_id, so its grain is gold's. The differences are business rules Phoenix computes itself. Moving them out of Phoenix is tracked separately; this is the current list.
| Concept | Core Concepts | Gold | Phoenix |
|---|---|---|---|
| No response | A variance means nothing until the payer answers | "No Response" opportunity type | Counts the full expected amount as an underpayment |
| Underpayment | Expected greater than actual | opportunity_type uses allowed minus paid | Expected minus allowed, matching the doc |
| Tolerance | Per charge; the greater of a percentage or a flat amount | One flat threshold per encounter | One flat threshold, default $1, plus a $0.005 floor |
| Recovery amount | Total movement, and change since the appeal (allowed-at-appeal captured at submission) | Not computed | Both views; allowed-at-appeal is recomputed from the ledger with its own recency rule |
| Disposition | A decision (appeal, will not appeal, rebill, write-off, fix at source) made before appeal stages exist | Not modeled | "Will Not Appeal" is one of 19 appeal stages |
| Root cause | An attribute of every variance, appealed or not | Not modeled | Recorded on a project's encounter, only when moved to Will Not Appeal |
| Project | An encounter is actionable in one project at a time | — | One active project per appeal type |
| Label | On encounters, locations, providers, and so on | — | Encounters only |
| Filing deadline | Date of service plus the contract's dispute window, on the encounter | Column exists, always null | Not shown without it |