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);

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 California medical-legal bills, including QME and AME workflows.