Billing settings and saved profiles

Use the built-in Settings tab

React 0.64.0 includes a Settings tab by default in ConnectedBillingWorkspace and BillingDashboard. It uses BillingSettings for practice information, billing and rendering providers, service locations, and W-9 upload. You do not need a separate settings page.

"use client";
import { ConnectedBillingWorkspace } from "@mindbill/react";

export function BillingPage({ canManageBilling }: { canManageBilling: boolean }) {
  return <ConnectedBillingWorkspace
    sessionEndpoint="/api/mindbill/session"
    showSettings={canManageBilling}
    billingSettings={{ sessionEndpoint: "/api/mindbill/settings-session" }}
  />;
}
// showSettings defaults to true. Set false to hide the tab.
// Optionally set initialView="settings" to open the workspace there.

showSettings defaults to true; set it to false to hide the tab, or match it to the user's role as above. Pass billingSettings for a dedicated administrator session. When omitted, the workspace reuses its main connection; BillingDashboard uses the default /api/mindbill/session endpoint. The server still requires organization:manage: showing a tab never grants permissions or changes the scopes minted by your host.

Use initialView="settings" on ConnectedBillingWorkspace to open settings first. Both dashboards accept onSettingsSaved(profile), where profile is the saved OrganizationProfileData, so your host can refresh any profile-derived state it owns. Keep sensitive profile values out of logs.

Standalone settings and first-run setup

BillingSettings is the compact settings editor. OrganizationOnboarding provides the guided first-run version. Both save to the authenticated MindBill organization and include practice information, billing and rendering providers, service locations, and W-9 upload. Keep your existing app navigation and authentication.

"use client";
import { BillingSettings, OrganizationOnboarding } from "@mindbill/react";

// Mount inside your existing administrator-only practice settings page.
export function PracticeSettings() {
  return <BillingSettings sessionEndpoint="/api/mindbill/settings-session" />;
}

// First-run wizard: billing provider, rendering providers, locations, W-9, review.
export function FirstTimeSetup() {
  return <OrganizationOnboarding
    sessionEndpoint="/api/mindbill/settings-session"
    onCompleted={() => { window.location.href = "/billing"; }} />;
}

Your /api/mindbill/settings-session route is a host endpoint you implement. Authenticate the current user, verify their practice administrator role, resolve the organization credential on your server, and mint a short-lived browser session granting organization:manage. Apply the same origin, tenant, and session protections as your billing endpoint.

Choose the provider that belongs on the bill

Start with Billing providers: the person or organization requesting payment. Its tax ID appears in CMS-1500 box 25; its name, pay-to address, phone, and NPI populate boxes 33 and 33a. The selected Rendering provider identifies the clinician who performed the service, including box 24J. The Service location supplies the address where the service occurred in box 32; the place-of-service code describes the setting in box 24B.

Organization details holds your organization's legal name and contact information. It is not an additional billing provider and does not replace the provider selected on a bill. These details still contribute to the onboarding checklist, so complete them when the checklist requests them. Saving a profile does not rewrite an already submitted bill.

These roles follow the NUCC CMS-1500 instruction manual; applicable payer and state instructions also govern claim completion.

Manage team access and custom claims administrators

React 0.65.0 organizes the settings editor into Billing profiles, Claims administrators, and Team. The administrator and team lists load only when their section is opened. For custom claims administrators, add a destination with a name and at least one fax, email, or mailing address, edit its contact details, or remove it from future choices. Removal preserves historical bill snapshots. This organization-specific contact does not create an electronic payer route in the shared directory. See the custom administrator API.

Team settings manage existing MindBill login accounts, not accounts or roles in your application. Authorized administrators can change an eligible account's role or active state. This integration does not invite or create users. Protected accounts may be displayed without edit controls.

Team administration requires a separately delegated team:manage browser permission backed by the server key's orgs:team:write scope. organization:manage alone does not grant it. Resolve the host user's authority on your server before granting either permission. Server-only callers use orgs:team:read to list accounts and orgs:team:write to update them. Bill- and customer-scoped credentials cannot manage these shared settings. See the team API.

Physician signature setup remains in MindBill rendering-provider settings. Email recipient invitations and digests use the separate notification settings component and trusted server adapter.

Use saved choices in the submission form

From React 0.62.0, the connected submission form automatically loads saved billing providers, rendering providers, and service locations when you omit profileOptions. Pass billingSettings with a separate administrator session to offer the prebuilt Add/edit settings flow. Ordinary bill creators need an organization-wide bills:create session to read these choices; they do not need settings write permission. Keep known case values in initialBill and let the user review their selection before submitting.

// Requires @mindbill/react >=0.62.0.
"use client";
import { BillSubmissionForm, type BillSubmissionFormProps,
  type BillSubmissionInput } from "@mindbill/react";

export function ProfileBasedBill({ initialBill, canManageBilling }: {
  initialBill: BillSubmissionInput; canManageBilling: boolean;
}) {
  return <BillSubmissionForm initialBill={initialBill}
    sessionEndpoint="/api/mindbill/session"
    profileDisplay="compact"
    {...(canManageBilling ? { billingSettings: {
      sessionEndpoint: "/api/mindbill/settings-session"
    } } : {})} />;
}
// The connected form reads saved choices automatically when profileOptions is omitted.
// The billing endpoint needs organization-wide bills:create, not organization:manage.
// billingSettings enables the prebuilt Add/edit settings flow. Its SEPARATE endpoint
// must enforce the administrator role server-side and grant organization:manage.
// Hiding a button is not an authorization check. Omit billingSettings for other users.
// Existing case values remain unchanged until the user explicitly selects a profile.

// Host-managed alternative: explicit choices override automatic organization lookup.
export function HostProfileBill({ initialBill, savedBillingProvider,
  savedRenderingProvider, savedServiceLocation }: {
    initialBill: BillSubmissionFormProps["initialBill"];
    savedBillingProvider: NonNullable<BillSubmissionInput["billingProvider"]>;
    savedRenderingProvider: NonNullable<BillSubmissionInput["renderingProvider"]>;
    savedServiceLocation: NonNullable<BillSubmissionInput["serviceLocation"]>;
  }) {
  const profileOptions = {
    billingProviders: [{ id: "practice-1", label: "Main practice", value: savedBillingProvider }],
    renderingProviders: [{ id: "doctor-1", label: "Rendering doctor", value: savedRenderingProvider }],
    serviceLocations: [{ id: "office-1", label: "Main office", value: savedServiceLocation }],
  };
  return <BillSubmissionForm initialBill={initialBill} profileOptions={profileOptions}
    profileDisplay="compact" sessionEndpoint="/api/mindbill/session" />;
}
// profileOptions={} also suppresses the organization-wide lookup when it is unwanted.
// Bill-scoped sessions cannot read organization-wide choices. Do not widen access.
// Omit profileDisplay (or use "expanded") to show all fields.
// Selecting a profile does not mutate the saved profile.
// SSN-backed choices retain savedProviderId; the server resolves the identifier.
// Never put taxIdLast4 in taxId, browser storage, telemetry or agent prompts.
// Settings supports taxIdType: "EIN" | "SSN" (default EIN).
// Saved SSNs are encrypted. Responses contain empty taxId, taxIdLast4 and
// taxIdConfigured. In settings: blank preserves, replacement changes, clear removes.
// Custom settings API writes: omit taxId to preserve; taxId: "" explicitly clears.
// Do not send response-only taxIdLast4/taxIdConfigured in a settings write.

Choosing a profile fills the bill snapshot. Editing a bill does not silently update the saved practice profile. Corrections create a reviewed replacement submission; confirm providers, location, dates, diagnoses, charges, and attachments again.

Choose one owner for the W-9

When MindBill owns the practice settings, upload the W-9 through the settings component. The server uses the saved organization W-9 for eligible organization-wide submissions. When your host owns the document, supply the reviewed PDF as a w9 attachment through BillSubmissionForm or the atomic bill API. Do not upload a second copy just to render a settings screen.

For host-owned uploads, W9Upload can show upload, extraction, retry, and review states using your callbacks. See W-9 storage and attachment examples.

Keep administrative and billing permissions separate

• Settings administrators: an authorized organization:manage session can change shared practice settings. A dedicated settings endpoint keeps this permission separate from ordinary billing sessions.
• Bill creators: an organization-wide bills:create session can read masked billing choices and submit bills.
• Case-only users: a bill-scoped session cannot list shared practice profiles. Pass explicitly authorized host choices when appropriate; never widen the session to make a dropdown work.

Saved SSNs are masked. Preserve savedProviderId references rather than copying the last four digits into a tax ID field. In custom settings writes, omit taxId to preserve it and send an empty string only to explicitly clear it. Keep tax identifiers out of logs and browser storage.

Verify before the first live bill

In sandbox, save a synthetic provider and location, create a bill using those choices, reopen the form, and verify a correction retains the expected snapshot. Confirm a non-administrator cannot change settings. Test the empty profile state, a failed profile request, and your W-9 ownership path. Use the sandbox workflow to inspect the resulting documents without contacting a payer.