The bill resource

Collect locally, then submit one exact snapshot

Workers' compensation bills carry more claim context than an ordinary patient invoice. Collect and edit the patient, injury, claims administrator, employer, providers, place of service, diagnoses, service lines, and attachments in your application before calling MindBill.

MindBill has no public draft bill. A successful request creates the bill with submitted as its first status and freezes the submitted values so later profile changes cannot rewrite billing history.

Create and submit atomically

Send the bill snapshot, routing choice, and documents in one operation. The connected React component does this directly; server-only integrations can use the Node SDK shown below. Use an idempotency key tied to the logical submission so a network retry cannot create a duplicate.

npm install @mindbill/node@latest

First look up the claims administrator and select an electronic payer route from its payers array. In this example, selectedAdministrator is that directory result, selectedPayer is the selected payer, and saveBillId is your own persistence function. Replace the synthetic bill fields and PDF with reviewed sandbox data.

import { readFile } from "node:fs/promises";
import { MindBillClient } from "@mindbill/node";

const apiKey = process.env.MINDBILL_API_KEY;
if (!apiKey) throw new Error("Set MINDBILL_API_KEY on your server");
const mindbill = new MindBillClient({ apiKey });
const finalReportBytes = await readFile("./final-report.pdf");

const bill = await mindbill.createAndSubmitBill({
  bill: {
    externalId: "report_9f7a",
    billingMode: "med_legal",
    patient: {
      externalId: "patient_42",
      firstName: "Alex",
      lastName: "Morgan",
      dateOfBirth: "1984-03-12",
      address: {
        line1: "100 Main St",
        city: "Fresno",
        state: "CA",
        postalCode: "93721",
      },
    },
    claim: {
      externalId: "injury_81",
      claimNumber: "WC-44871",
      employer: "Example Foods, Inc.",
      dateOfInjury: "2026-02-14",
      injuryState: "CA",
      claimsAdministrator: {
        id: selectedAdministrator.id,
        name: selectedAdministrator.name,
        payerId: selectedPayer.key,
      },
    },
    service: { date: "2026-08-26" },
    billingProvider: {
      name: "Northstar Evaluations",
      taxId: "123456789",
      npi: "1234567893",
      phone: "5595550100",
      address: { line1: "200 Market St", city: "Fresno", state: "CA", postalCode: "93721" },
    },
    renderingProvider: {
      name: "Morgan Chen, MD",
      npi: "1234567893",
      taxonomy: "2084P0800X",
      licenseNumber: "A12345",
      licenseState: "CA",
    },
    serviceLocation: {
      name: "Fresno Exam Office",
      placeOfServiceCode: "11",
      address: { line1: "300 Pine Ave", city: "Fresno", state: "CA", postalCode: "93721" },
    },
    diagnoses: ["M25.562"],
    serviceLines: [{ code: "ML201", modifiers: ["95"], units: 1 }],
  },
  submission: { route: "ebill" },
  documents: [{
    filename: "final-report.pdf",
    documentType: "final_report",
    contentBase64: finalReportBytes.toString("base64"),
    externalId: "document_88",
  }],
}, "submit-report-9f7a");

await saveBillId(bill.id);

Let MindBill calculate professional fees

For a California CMS-1500 bill with billingMode: "professional", MindBill calculates supported lines from the complete bill context. ZIP and place of service are not repeated on each ordinary service line: they come from bill.serviceLocation. Provider type comes from bill.renderingProvider.taxonomy, and a line's date defaults to bill.service.date.

The following is deliberately only the pricing-relevant excerpt. A real submission must also contain the patient, claim, provider, payer, diagnoses, and other required fields shown in the create-bill reference.

// Pricing-relevant excerpt from an otherwise complete bill request.
// ZIP, place of service, and taxonomy live on the parent bill—not the line.
{
  "billingMode": "professional",
  "claim": {
    "injuryState": "CA"
  },
  "service": {
    "date": "2026-09-22"
  },
  "renderingProvider": {
    "taxonomy": "2084P0800X"
  },
  "serviceLocation": {
    "placeOfServiceCode": "11",
    "address": {
      "postalCode": "94403"
    }
  },
  "serviceLines": [{
    "code": "99213",
    "units": 1
  }]
}

// Returned service-line excerpt. Amounts here are dollars.
{
  "code": "99213",
  "charge": 181.68,
  "pricing": {
    "status": "calculated",
    "expectedAmount": 181.68,
    "scheduleMaximumAmount": 181.68,
    "statutoryMaximumAmount": 181.68,
    "reimbursementBasis": "statutory_schedule",
    "warnings": []
  }
}

For supported ordinary physician and office physical-therapy lines, serviceLines[].charge is optional. MindBill calculates the applicable fee and uses a matching practice charge schedule when one exists; otherwise the billed charge defaults to the calculated statutory maximum. The statutory maximum itself still reflects the date, ZIP/locality, place of service, provider type, code, units, modifiers, and any required context.

If you supply charge, it is the extended billed-charge override in dollars, not a unit price and never a caller-selected allowance. A charge of 999 can remain the submitted charge while pricing.expectedAmount stays capped at the verified schedule maximum. Quote fields explicitly ending in Cents use integer cents instead.

Send feeContext when the actual service differs from the standard inferred facts or needs details that cannot be derived from the bill. Explicit context wins over defaults. Read pricing.status, expectedAmount, scheduleMaximumAmount, reimbursementBasis, sources, and warnings from each returned line. A review warning means no verified reimbursement was saved; it never turns the submitted charge into an allowance.

The standalone quote API represents some of these same facts differently: POST /fee-quotes/ca/claim accepts lines[].serviceZip and lines[].physicianContext.placeOfService. Do not copy those quote-only field names into bill.serviceLines[]. For the exact quote shape, encounter-wide NCCI and unit-edit assessment, specialty inputs, calculation steps, and source citations, use the California fee calculator guide.

Find submitted bills from your records

Store the stable MindBill bill ID after successful submission, or find submitted bills later using your external identifiers.

const page = await mindbill.listBills({
  externalId: "report_9f7a",
  patientExternalId: "patient_42",
  claimExternalId: "injury_81",
  limit: 25,
});

For staff searches, use q to match words across patient and claims-administrator names, bill and claim IDs, external IDs, statuses, procedure codes, and dates. Every word must match somewhere in the bill; matching ignores case. Combine this with dateField=service or dateField=submitted and inclusive from/to dates in YYYY-MM-DD format. See all bill query parameters.

Use canonical patientId, renderingProviderId, and claimsAdminId parameters to filter related bills. The dashboard supplies patient and administrator choices across the authorized bill inventory, independent of pagination and active filters. React 0.67.0 connects detail names to these filters by default in ConnectedBillingWorkspace; host callbacks can override navigation.

ConnectedBillSearch and the workspace registry provide these controls out of the box. Apply text and dates with Search or Enter; status, age, patient, rendering-provider, and claims-administrator filters apply immediately. Clear resets the search and filters. BillingDashboard instead filters the array supplied by your host immediately.

Billing-mode availability

Use med_legal for workers' compensation medical-legal bills, including California QME and AME workflows. Set claim.injuryState to the actual claim state; supported CMS-1500, UB-04, ADA, and NCPDP bills can be created for claims in all 50 states. Available payer and delivery routes still depend on the selected claims administrator and form. See the partner coverage guide.