Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/sputhenofficial/claimjumper/llms.txt

Use this file to discover all available pages before exploring further.

All data contracts in ClaimJumper are defined as Zod schemas in lib/schemas.ts. TypeScript types are derived with z.infer<typeof Schema> — there are no hand-written interfaces for domain objects. Every model output is validated against these schemas before it is used anywhere downstream: if an OpenAI response does not satisfy the schema, parsing throws and the error propagates to the pipeline’s error boundary.

​
Remittance & Claim

These schemas model the structured output of the ingest stage — the parsed representation of a raw EOB remittance screenshot.

​
RemittanceMetaSchema / RemittanceMeta

Payer-level header data present on every remittance document. Extracted once per EOB and shared across all claims on the same remittance. 
type RemittanceMeta = {
  payer: string;                        // min 1 char
  provider: string;                     // min 1 char
  provider_npi: string;                 // min 1 char
  notice_date: string;                  // ISO date (YYYY-MM-DD)
  payment_date: string;                 // ISO date (YYYY-MM-DD)
  eft_trace: string;                    // min 1 char
  code_legend: CodeLegendEntry[];       // min 1 entry
}
notice_date and payment_date are validated as ISO date strings by Zod’s .date() refinement. code_legend must contain at least one entry — the pipeline relies on it to resolve CARC and RARC definitions for drafting.

​
ClaimMetaSchema / ClaimMeta

Claim-level header data identifying the patient and claim. 
type ClaimMeta = {
  claim_id: string;             // min 1 char
  patient_name: string;         // min 1 char
  service_date: string;         // ISO date (YYYY-MM-DD)
  claim_received_date: string;  // ISO date (YYYY-MM-DD)
}
service_date is the date of service for the claim as a whole; individual service lines carry their own service_date fields via ServiceLineSchema.

​
ServiceLineSchema / ServiceLine

A single denial line extracted from a claim. Represents one procedure code and its associated adjustment reason codes. 
type ServiceLine = {
  line_number: number;             // positive integer
  service_date: string;            // ISO date (YYYY-MM-DD)
  procedure_code: string;          // min 1 char
  description: string;             // min 1 char
  billed_amount: number;           // nonnegative
  allowed_amount: number;          // nonnegative
  paid_amount: number;             // nonnegative
  patient_responsibility: number;  // nonnegative
  group_code: string;              // min 1 char (e.g. "CO", "PR", "OA")
  carc: string;                    // min 1 char — Claim Adjustment Reason Code
  rarc: string | null;             // min 1 char if present — Remittance Advice Remark Code
  notes: string | null;            // min 1 char if present — free-text annotation
}
rarc and notes are explicitly nullable() in Zod rather than optional — the model must emit null for absent values rather than omitting the field entirely. This ensures Structured Outputs can enforce strict JSON schema compliance.

​
ClaimSchema / Claim

A single independently processable claim extracted from a remittance, grouping the shared remittance header, the claim metadata, and all service lines belonging to that claim. 
type Claim = {
  remittance: RemittanceMeta;
  claim: ClaimMeta;
  lines: ServiceLine[];  // min 1 line
}
The remittance field is repeated on every Claim rather than hoisted — this makes each Claim self-contained and avoids shared-reference bugs when claims from the same EOB are processed in parallel.

​
IngestOutputSchema / IngestOutput

The direct output of the ingest pipeline stage: an array of at least one Claim. 
type IngestOutput = Claim[];  // min 1 claim
The Responses API Structured Outputs feature requires a JSON object at the schema root — a bare array is not valid as a top-level schema. IngestResponseSchema wraps IngestOutputSchema in an object envelope for this reason:
// Used as the Structured Outputs schema; claims array is unwrapped before use downstream.
const IngestResponseSchema = z.object({
  claims: IngestOutputSchema,  // IngestOutputSchema = z.array(ClaimSchema).min(1)
});
The ingest pipeline extracts response.claims after parsing and passes the unwrapped IngestOutput to the rest of the pipeline.

​
Triage

These schemas capture the AI triage model’s classification of a denial line and the invariant-enforcement layer applied on top of it.

​
LaneSchema / Lane

The five possible disposition lanes for a denial line. 
type Lane =
  | "appeal"           // File a formal appeal with the payer
  | "corrected_claim"  // Resubmit with corrected billing information
  | "patient_bill"     // Bill the patient for their responsibility
  | "write_off"        // Write off as a contractual or non-recoverable adjustment
  | "human_review"     // Escalate for manual review — model confidence too low or conflicting signals
Lane assignment is the primary output of the triage stage and drives both draft generation and queue filtering downstream.

​
AdjustmentLineSchema / AdjustmentLine

A reduced, triage-focused view of a service line, constructed in the route handler by projecting the fields relevant to denial classification. This is what the triage model receives — not the full ServiceLine. 
type AdjustmentLine = {
  group_code: string;    // min 1 char
  carc: string;          // min 1 char
  rarc?: string;         // min 1 char if present (optional, not nullable)
  billed_amount: number; // nonnegative
  description: string;   // min 1 char
  notice_date: string;   // ISO date (YYYY-MM-DD)
  notes?: string;        // min 1 char if present (optional, not nullable)
}
Unlike ServiceLineSchema, rarc and notes are optional (not nullable) here — the field is omitted entirely when absent, matching the constructor logic in the route handler.

​
TriageModelOutputSchema / TriageModelOutput

The raw structured output from the triage model before invariant enforcement. Contains the lane decision plus supporting reasoning. 
type TriageModelOutput = {
  lane: Lane;
  root_cause: string;           // min 1 char — concise root cause label
  rationale: string;            // min 1 char — full reasoning prose
  evidence_needed: string[];    // each min 1 char — list of required supporting documents
  confidence: number;           // 0–1 inclusive
  recovery_probability: number; // 0–1 inclusive
}
confidence represents the model’s certainty in its lane assignment. recovery_probability is the model’s estimate that the denial is recoverable (through appeal or corrected claim). Both are bounded [0, 1] by Zod .min(0).max(1).

​
DenialTriageSchema / DenialTriage

Extends TriageModelOutputSchema with an overrides array appended by the invariants layer after model inference. Invariants may force a lane change or inject override notes without altering the model’s original reasoning fields. 
type DenialTriage = TriageModelOutput & {
  overrides: string[];  // each min 1 char — invariant override messages
}
overrides is an empty array when no invariants fired. Any injected triage function passed via PipelineDependencies must return an already-enforced DenialTriage.

​
Prioritization

​
PrioritizedLineSchema / PrioritizedLine

The output of the prioritization stage. Wraps a triage-annotated AdjustmentLine with scheduling information and a composite priority score used to sort the work queue. 
type PrioritizedLine = {
  line: AdjustmentLine;    // the denial line that was triaged
  triage: DenialTriage;    // full triage output including overrides
  deadline: string;        // ISO date (YYYY-MM-DD) — calculated appeal deadline
  urgency: number;         // 0–1 — proximity to deadline
  priority_score: number;  // finite — composite sort key (higher = more urgent)
}
priority_score is validated as .finite() — Infinity, -Infinity, and NaN are rejected. The prioritization stage uses today (injected or live UTC) to compute deadline and urgency relative to the notice_date on the denial line.

​
Draft

​
DraftInputSchema / DraftInput

The explicit, validated input to the draft pipeline stage. Keeps the full parsed Claim and ServiceLine available to the model rather than the lossy AdjustmentLine projection, ensuring citations can be verified against actual parsed field values. 
type DraftInput = {
  claim: Claim;
  service_line: ServiceLine;
  triage: DenialTriage;
}
adaptForDrafting() in lib/pipeline/draft.ts constructs and validates a DraftInput via DraftInputSchema.parse() before passing it to the model.

​
DraftCitationSchema / DraftCitation

A single verifiable citation in a generated draft artifact. Every claim made in the draft body must be grounded in a citation that the server can resolve and verify against the parsed input. 
type DraftCitation = {
  source: "parse" | "legend";
  field_path: string;  // min 1 char
  value: string;       // canonical string representation of the cited field
}

​
DraftArtifactSchema / DraftArtifact

The final, validated draft artifact stored on a QueueItem. Produced by the draft pipeline stage and returned as part of the TriageResponse. 
type DraftArtifact = {
  lane: Lane;                  // matches the triage lane that triggered drafting
  title: string;               // min 1 char — display title (e.g. "Appeal Draft")
  content: string;             // min 1 char — full draft body text
  citations: DraftCitation[];  // grounding citations for claims in the body
}
lane is one of "appeal", "corrected_claim", or "human_review" — the draft pipeline is not invoked for "patient_bill" or "write_off" lanes. For "human_review", the content is a structured review brief generated without a model call; citations will be an empty array.

​
Schema validation pattern

ClaimJumper uses the OpenAI Responses API’s Structured Outputs feature to constrain model output to a known JSON shape, then validates the parsed response with Zod before it enters the pipeline. The two OpenAI client helpers in lib/openai.ts implement this pattern: 
// Text-only model call (triage, draft)
export async function responseWithSchema<TSchema extends z.ZodType>(
  model: string,
  systemPrompt: string,
  input: string,
  schema: TSchema,
  options: { effort: Effort },
): Promise<z.infer<TSchema>> {
  // ...
  const response = await client.responses.create({
    // ...
    text: {
      format: {
        type: "json_schema",
        name: "structured_response",
        strict: true,
        schema: z.toJSONSchema(schema),  // derive JSON Schema from Zod schema
      },
    },
  });

  return schema.parse(JSON.parse(response.output_text));  // validate before returning
}

// Vision model call (ingest) — same schema enforcement, image input
export async function responseWithImageSchema<TSchema extends z.ZodType>(
  model: string,
  systemPrompt: string,
  imageBytes: Uint8Array,
  schema: TSchema,
  options: { effort: Effort; mimeType: string },
): Promise<z.infer<TSchema>> { /* ... same pattern ... */ }
z.toJSONSchema(schema) converts the Zod schema to a JSON Schema object that OpenAI uses to constrain generation. After the API responds, schema.parse(JSON.parse(response.output_text)) re-validates the output with full Zod semantics — including refinements like .min(), .date(), and .finite() that JSON Schema cannot always enforce at the API level.

Build docs developers (and LLMs) love

Get started for freeTalk to us