ClaimJumper Data Model: Types, Shapes, and Field Semantics

ClaimJumper’s data model flows from parsed remittance data through triage decisions and prioritization scoring to draft artifacts. Remittance images are extracted into structured Claim objects by the ingest pipeline, each claim’s denied lines are normalized into AdjustmentLine records for triage, and the result is assembled into a PrioritizedLine that carries a deadline, an urgency score, and an optional DraftArtifact. The final TriageResponse returned to the UI holds every QueueItem the biller needs to act on. This page describes the shape and semantics of each type in the order it appears in that pipeline.

`RemittanceMeta`

RemittanceMeta is extracted from the remittance header by the ingest step. Every Claim in a batch shares the same RemittanceMeta because a single remittance document covers one payer-provider payment event.

payer

string

required

Payer name from the remittance header (e.g. "Meridian Health Plan").

provider

string

required

Provider name as printed on the remittance (e.g. "North Valley Medical Group").

provider_npi

string

required

10-digit National Provider Identifier exactly as printed. No formatting is applied — leading zeros are preserved.

notice_date

string

required

ISO 8601 calendar date (YYYY-MM-DD) of the remittance notice. This field drives appeal deadline calculation: calculateAppealDeadline() adds 5 presumed-receipt days then 120 redetermination days to arrive at the filing deadline.

payment_date

string

required

ISO 8601 calendar date on which payment was issued.

eft_trace

string

required

EFT trace number from the payment header (e.g. "MHP-260614-784391").

code_legend

CodeLegendEntry[]

required

Every CARC and RARC definition printed in the remittance footer’s “Adjustment and Remark Code Legend.” Must contain at least one entry. These definitions are the canonical source for draft artifact citations — they are never inferred from model knowledge.

`CodeLegendEntry`

Each entry in code_legend captures a single code definition exactly as it appears on the remittance page.

code_system

"CARC" | "RARC"

required

Whether this is a Claim Adjustment Reason Code (CARC) or a Remittance Advice Remark Code (RARC).

code

string

required

The code identifier. Preserves leading zeros and alphanumeric codes exactly as printed (e.g. "16", "M51", "N115"). Never normalized or zero-stripped.

definition

string

required

The verbatim definition printed in the legend. Never inferred from model knowledge — if a code appears in the legend, this field contains its exact printed text.Example entries from eob-001:

[
  { "code_system": "CARC", "code": "29",   "definition": "The time limit for filing has expired." },
  { "code_system": "CARC", "code": "50",   "definition": "These are non-covered services because this is not deemed a medical necessity by the payer." },
  { "code_system": "RARC", "code": "N115", "definition": "This decision was based on a Local Coverage Determination (LCD)." }
]

`ClaimMeta`

ClaimMeta captures the claim-level identifiers extracted from each individual claim block within the remittance.

claim_id

string

required

Payer-assigned claim identifier (e.g. "MHP-CLA-482901").

patient_name

string

required

Patient name as printed on the remittance.

service_date

string

required

ISO 8601 date of service at the claim level. Individual service lines carry their own service_date which may differ when a claim spans multiple dates.

claim_received_date

string

required

ISO 8601 date the claim was received by the payer. Used together with service_date when constructing timely-filing appeal evidence.

`ServiceLine`

ServiceLine represents one line of a claim as adjudicated on the remittance. Every financial amount is nonnegative. The rarc and notes fields are explicitly nullable — they are null when absent on the remittance, never omitted or defaulted to an empty string.

line_number

number

required

Positive integer identifying the line within the claim (1-indexed as printed).

service_date

string

required

ISO 8601 date of service for this specific line.

procedure_code

string

required

CPT or HCPCS procedure code (e.g. "99285", "71046").

description

string

required

Human-readable description of the procedure as printed on the remittance line.

billed_amount

number

required

Amount billed by the provider. Nonnegative.

allowed_amount

number

required

Amount allowed by the payer. Nonnegative. May be 0 for fully denied lines.

paid_amount

number

required

Amount actually paid to the provider. Nonnegative.

patient_responsibility

number

required

Amount assigned to the patient (coinsurance, copay, deductible). Nonnegative.

group_code

string

required

Standard X12 group code classifying who is responsible for the adjustment (e.g. CO, PR, OA, PI, CR). See the Adjustment Codes reference for routing implications.

carc

string

required

Claim Adjustment Reason Code. Read together with group_code and rarc, never in isolation.

rarc

string | null

required

Remittance Advice Remark Code. null when no RARC appears on this line — never coerced to an empty string. The triage model treats a null RARC differently from a present one.

notes

string | null

required

A claim-level remark or note copied to all service lines of that claim during ingest. null when no remark is present. Example: "Clearinghouse acknowledgment on file showing original submission 2026-03-02."

`Claim`

Claim is the independently processable unit produced by ingest(). Each Claim carries the full remittance context alongside a single claim block and its service lines, so downstream pipeline steps never need to re-join across a batch.

remittance

RemittanceMeta

required

The remittance header shared across all claims in the batch.

claim

ClaimMeta

required

Identifiers and dates for this specific claim.

lines

ServiceLine[]

required

One or more service lines adjudicated under this claim. The schema enforces a minimum of one line.

`AdjustmentLine`

AdjustmentLine is the normalized, flattened view of a service line used by the triage model and the prioritization step. It is produced by adaptForPrioritization(), which promotes notice_date from RemittanceMeta and copies the denial-relevant fields from ServiceLine. The rarc and notes fields are optional rather than nullable: they are omitted entirely when absent, which allows the Zod schema to produce clean objects without null sentinel values for the model.

group_code

string

required

X12 group code from the service line.

carc

string

required

Claim Adjustment Reason Code.

rarc

string

Remittance Advice Remark Code. Omitted (not present on the object) when the service line had no RARC.

billed_amount

number

required

Nonnegative billed amount, carried forward for priority score calculation.

description

string

required

Procedure description from the service line.

notice_date

string

required

ISO 8601 date promoted from RemittanceMeta.notice_date. This is the anchor date for calculateAppealDeadline().

notes

string

Claim-level remark. Omitted when absent — not set to null.

`DenialTriage`

DenialTriage is the triage model’s output (TriageModelOutput) extended with an overrides array populated by enforceInvariants() after the model responds. The overrides field records which safety rules fired and what lane changes were made, providing a human-readable audit trail.

lane

Lane

required

The resolved resolution lane after invariant enforcement. One of:

Value	Meaning
`appeal`	File a formal appeal with supporting documentation
`corrected_claim`	Resubmit with corrected billing information
`patient_bill`	Balance due from patient; route to patient statement
`write_off`	Provider absorbs the adjustment; no further action
`human_review`	Escalated — biller must decide before any action is taken

root_cause

string

required

Concise label for the denial reason (e.g. "Missing or invalid procedure code information.").

rationale

string

required

Explanation citing the specific Group Code, CARC, and RARC combination that drove the lane decision. Only codes and facts present in the parsed input are cited — the model never invents policy numbers, LCD identifiers, or clinical facts.

evidence_needed

string[]

required

Ordered list of documents or data the biller must attach for the chosen lane to succeed. Empty array is valid when no additional evidence is required.

confidence

number

required

Model confidence in the lane assignment, expressed as a value between 0 and 1 inclusive. Values below 0.6 trigger an automatic override to human_review.

recovery_probability

number

required

Estimated probability that pursuing the assigned lane will result in payment recovery, between 0 and 1. Used directly in the priority score formula: billed_amount × recovery_probability × urgency.

overrides

string[]

required

Human-readable descriptions of any invariant rules that fired and modified the model’s raw output. Empty array ([]) when no invariants changed the lane. Example: ["CO invariant: lane changed from patient_bill to human_review"].

`PrioritizedLine`

PrioritizedLine is the output of the prioritize() step. The work queue is sorted first by deadline ascending, then by priority_score descending, so the most urgent high-value lines surface at the top.

line

AdjustmentLine

required

The normalized adjustment line being prioritized.

triage

DenialTriage

required

The triage decision (including any invariant overrides) for this line.

deadline

string

required

ISO 8601 date computed by calculateAppealDeadline(line.notice_date): notice date + 5 presumed-receipt days + 120 redetermination days.

urgency

number

required

A 0–1 score computed as clamp((125 - daysRemaining) / 125, 0, 1), where daysRemaining is calendar days from today to deadline. A line due tomorrow has urgency near 1; a freshly opened line with 125+ days remaining has urgency near or at 0.

priority_score

number (finite)

required

Composite score used for queue ordering within the same deadline bucket:

priority_score = billed_amount × recovery_probability × urgency

A $2,840 line with recovery_probability = 0.35 and urgency = 0.80 scores 794.4. Higher is worked first.

`DraftArtifact`

DraftArtifact holds the actionable output produced by the draft step for lanes that require written follow-up. The artifact is scoped to a single service line.

lane

Lane

required

The lane this artifact was drafted for — always matches the DenialTriage.lane of the parent QueueItem.

title

string

required

Display title. Conventionally one of:

"Appeal Draft" — for appeal lanes
"Corrected Claim Worklist" — for corrected_claim lanes
"Human Review Required" — for human_review lanes

content

string

required

The full text of the drafted artifact — appeal letter body, corrected-claim checklist, or human-review summary. All cited values in the content are grounded in the citations array.

citations

DraftCitation[]

required

Structured citations linking each claim in the artifact body back to its source field. Each DraftCitation carries a source ("parse" for extracted claim data or "legend" for the code definitions printed on the remittance), a field_path identifying the source location, and a value string.

`QueueItem` and `TriageResponse`

These are the top-level types returned by ClaimJumper’s triage API endpoint. QueueItem binds the full parsed claim, the specific service line being worked, its prioritization record, and (when applicable) the drafted artifact. Keeping the full Claim on the item ensures the draft step always has access to rich context without needing to re-join. TriageResponse is the complete API response body: the ordered work queue plus the shared remittance metadata.

interface QueueItem {
  claim: Claim;
  serviceLine: ServiceLine;
  prioritized: PrioritizedLine;
  artifact?: DraftArtifact;  // present for appeal, corrected_claim, human_review
}

interface TriageResponse {
  items: QueueItem[];
  remittance: RemittanceMeta;
}

artifact is intentionally optional. The write_off and patient_bill lanes do not generate a drafted artifact — the triage decision itself is the actionable output.

API

Data Model

Documentation Index

​RemittanceMeta

​CodeLegendEntry

​ClaimMeta

​ServiceLine

​Claim

​AdjustmentLine

​DenialTriage

​PrioritizedLine

​DraftArtifact

​QueueItem and TriageResponse

Build docs developers (and LLMs) love

`RemittanceMeta`

`CodeLegendEntry`

`ClaimMeta`

`ServiceLine`

`Claim`

`AdjustmentLine`

`DenialTriage`

`PrioritizedLine`

`DraftArtifact`

`QueueItem` and `TriageResponse`