Build the payer packet

Choose the billing packet explicitly

For a California medical-legal bill, the payer packet commonly includes the final report, proof of service, required DWC forms, and the current W-9. The exact packet depends on the service and dispute.

• Preselect the final report, proof of service, required billing forms, and W-9 when your product already has them.
• Never silently attach medical records. Add them only when a user intentionally chooses them.
• Keep documents served on attorneys distinct from documents sent with the payer bill.
• Show the full packet before submission and let the user add or remove support.

Review fields and attachments in one component

The React BillSubmissionForm lets users review prefilled fields and PDFs, add or remove supporting documents, and submit the complete packet. Pass only the source documents chosen for billing: every supplied attachment is included unless removed, even if it has selected: false.

<BillSubmissionForm
  initialBill={billingSnapshot}
  attachments={selectedBillingDocuments}
  sessionEndpoint="/api/mindbill/submission-session"
  onSubmitted={({ billId }) => saveBillId(billId)}
/>

Send documents with the immutable snapshot

The connected component resolves selected source attachments and new uploads, encodes their PDF bytes, and includes them in the same atomic request as the bill data. For API-only integrations, perform the equivalent operation on your server. Store the returned bill ID only after success.

const report = await fetch(reportDownloadUrl);
if (!report.ok) throw new Error("Unable to load final report");
const contentBase64 = Buffer.from(await report.arrayBuffer()).toString("base64");

const bill = await mindbill.createAndSubmitBill({
  bill: billingSnapshot,
  submission: { route: "ebill" },
  documents: [{
    filename: "final-report.pdf",
    documentType: "final_report",
    contentBase64,
    externalId: "document_88",
    description: "Final medical-legal report",
  }],
}, "submit-report-9f7a");

Choose one owner for practice W-9 settings

If you want MindBill to store the practice profile and W-9, embed BillingSettings or OrganizationOnboarding with a separate, admin-authorized organization:manage session. Reuse the saved profile when prefilling future bills.

If your app already uploads, stores, and extracts W-9s, keep that source of truth. React 0.50.0's W9Upload provides the common UI through host callbacks; it does not upload to MindBill or run a parser itself. Reuse your existing server upload and extraction workflow, then reload the persisted document and extraction state:

import { W9Upload } from "@mindbill/react";

<W9Upload
  document={profile.w9} // { filename, addedAt? } or undefined
  extractionStatus={profile.w9ExtractionStatus}
  onUpload={async (file) => {
    await uploadPracticeW9(file); // YOUR authenticated host-server adapter
    await reloadPracticeProfile();
  }}
  onView={() => openAuthorizedW9()}
  onRetryExtraction={async () => {
    await retryPracticeW9Extraction();
    await reloadPracticeProfile();
  }}
  appearance={{ preset: "mindbill" }}
/>

Extraction statuses are idle, queued, processing, complete, not_found, and failed. Pass the real server state; upload success does not mean extraction succeeded. Continue your existing polling or refresh until extraction finishes, and let an authorized user review extracted billing details before using them.

onView and onRetryExtraction are optional. The adapter also accepts maxSizeBytes, disabled, className, style, and the shared appearance tokens. Ensure the upload limit matches your host server.

See practice settings for the complete save-once workflow and permission split.

Authorization and network support

When the payer needs an authorization letter or Medical Provider Network (MPN) document with the bill, attach the reviewed PDF with documentType: "other" and a clear filename and description. These files are optional; neither a filename nor an attachment establishes authorization or network participation. Use service.authorizationNumber for a supplied authorization number and, for treatment, serviceLines[].rfaItemId to link an eligible saved RFA item.

An RFA has its own signed request and clinical packet, destination, and transmission history. Follow the RFA workflow; submitting a bill does not submit an RFA.

Size limits

Documents travel base64-encoded inside the JSON body, and base64 adds about 33% to every file. Budget against the decoded PDF bytes:

Only PDFs are accepted; MindBill verifies the leading bytes of every document and rejects anything else with 415 invalid_pdf.

Document types