Integrate one customer at a time

Provision and isolate customers

Keep an account-scoped API key on your server. Create one MindBill organization for each customer with a stable, opaque externalId from your tenant database. Provisioning is automatic and returns an organization immediately; its initial configuring status is separate from readiness to submit live claims. Store the returned organizationId with the tenant.

curl https://app.mindbill.org/partner/v2/organizations \
  --request POST \
  --header "Authorization: Bearer $MINDBILL_ACCOUNT_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: tenant-42" \
  --data '{"externalId":"tenant_42","name":"Example Practice"}'

For each server request, authenticate your user, resolve the tenant from server-owned membership data, then send its saved ID in X-MindBill-Org-Id. An account key cannot use an organization outside its account. Use an organization-scoped key if a dedicated service should be confined to one customer. For React components, your server mints a short-lived browser session for that organization and the user's allowed actions; the browser token stays bound to that organization. See the customer organization guide for a complete session route.

Submit bills across states

The same bill creation API accepts workers' compensation medical-legal and treatment bills for claims in all 50 states, including CMS-1500, UB-04, ADA, and NCPDP formats where the selected form and delivery route support the claim. Set claim.injuryState to the claim's actual two-letter state, and use billingMode for the bill type. California OMFS fee calculation applies only when its jurisdiction and service context match; a different injury state does not invoke California-specific fee rules.

Search the claims-administrator directory and select an available payer and delivery route before submission. An accepted state code alone does not establish that every payer and delivery method is available. Check the returned payer choices for the actual claim and contact MindBill if the needed route is missing.

To submit CMS-1500 professional treatment bills with your own pricing, set bill.billingMode to professional and bill.pricingMode to manual in the atomic create-and-submit request. Supply an explicit serviceLines[].charge on every line and omit feeContext. The charge is the extended billed amount, not the payer's allowed amount. Manual mode skips the ordinary fee quote; specialized anesthesia and pharmacy lines still require the supported calculation workflow and can be rejected. The default automatic mode runs applicable schedule checks. Keep your own allowance estimate in your system; the bill API's pricing.expectedAmount is MindBill's separate estimate when available.

If billers in your product start a treatment bill before it is complete, save it as an unsent bill draft instead of keeping partial bills in your own database. Drafts belong to the integration, organization, and environment that saved them, are never validated for submission or sent, and become a bill only when you submit the completed bill with draft: { id, revision }. They require the organization's treatmentBilling capability.

An organization-wide integration may reference that organization's saved billing provider with billingProvider.savedProviderId instead of resending its full profile. Customer-scoped and bill-scoped credentials cannot use shared saved providers, and IDs cannot cross organization boundaries. See the pricing fields, provider settings, and full request schema.

Read EORs and payments

Use GET /partner/v2/bills/{billId}/eor after the payer issues an Explanation of Review (EOR). It returns available line-level billed, allowed, and payment-advice amounts; CARC adjustments and RARC remark codes; the payer claim-control number; and an authorized source EOR document when retained. The payer's reportedPaid advice is separate from paid amounts confirmed in the bill's payment ledger. Read bill status, totalPaid, and balanceDue for posted cash and balance. For newly processed 835 transmissions whose claims all map to one organization, follow raw835Files[].contentUrl to download the original X12 file. The link requires bill and organization access. Historical files and transmissions with unmatched or mixed-organization claims have no raw download. Some payer fields or source documents can be absent. See the EOR response and lifecycle guide.

MindBill records the payer's remittance and payment information for tracking. The payer pays the provider; MindBill does not receive or disburse the claim payment.

Synchronize status and payments

Consume signed webhooks for changes, verify each signature over the raw request body, and deduplicate by event ID. A webhook tells you to reconcile the current bill or EOR state. Delivery is at least once and can arrive out of order, so do not derive balances solely from callback order. MindBill retries failed deliveries up to ten attempts with increasing delays from 30 seconds to one hour. The organization's GET /partner/v2/events cursor stream lets you catch up after a receiver outage.

Create an account-wide webhook endpoint to receive all organizations through one receiver, or set organizationId on an endpoint to deliver only that customer's events. The signed event envelope carries organizationId so a shared receiver can route to its tenant. Keep endpoint secrets server-side, return a success response only after durable receipt, and use webhook delivery history to investigate failures.

curl https://app.mindbill.org/partner/v2/developer/account/webhook-endpoints \
  --request POST \
  --header "Authorization: Bearer $MINDBILL_ACCOUNT_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: tenant-42-webhook" \
  --data '{"url":"https://example.com/mindbill/webhooks","eventTypes":["bill.submitted","eor.received","payment.posted"],"organizationId":"org_example"}'

This endpoint requires an account-scoped key with account:write. Use your actual organization ID and public HTTPS receiver; omit organizationId to receive account-wide events.

Go live and reconcile usage

Accept the Business Associate Agreement (BAA) and configure billing once for the partner account. Your customer organizations do not each sign a separate MindBill BAA. Live access also depends on the account's approval and each selected organization's operational readiness. Check its returned status and required billing/provider settings before live submission. See the live access checklist.

The partner account has one Stripe customer and subscription for live usage across its organizations. Use an account-scoped key with account:read to retrieve a dated organization breakdown and final account invoices:

curl 'https://app.mindbill.org/partner/v2/developer/account/usage?from=2026-10-01&to=2026-10-31&interval=day' \
  --header "Authorization: Bearer $MINDBILL_ACCOUNT_KEY"

Filter by inclusive UTC from and to dates (up to 366 days), interval=day|week|month, and optionally organizationId. organizationBreakdown[] and series[] show gross metered submissions and usage before account credits and invoice taxes. metering shows delivery status counts. billing.invoices[] and billing.totals show final account invoice subtotal, total, credits, amount due, paid, and remaining for invoices overlapping the date range. Invoices stay account-wide even when usage is filtered by organization; MindBill does not allocate account discounts or tax to individual organizations. The developer dashboard charts this same report. Organization-fixed keys cannot read account-wide usage. See the usage report reference.