Build
Follow the whole bill lifecycle
Submission is the beginning, not the end. MindBill normalizes acknowledgments, EORs, payments, denials, reviews, corrected replacements, and closure.
From submission to payment
Submitted
MindBill sends the claim through the selected electronic or manual route.
Acknowledged
999 and 277CA responses report whether the electronic transaction was structurally accepted. Acceptance is not payment.
Adjudicated
The claims administrator issues an EOR explaining allowed amounts, payments, reductions, or denials.
Resolved
Record payment, correct a rejection, request review of a disputed amount, or close the bill.
Read status and EORs
The status endpoint is suitable for a case header, receivables list, or background reconciliation job. The EOR endpoint returns normalized line items plus the original PDF when available.
const { data: status } = await mindbill.getBillStatus(billId);
const { data: eor } = await mindbill.getBillEor(billId);
// Render status.state and status.balanceDue in your application.
// eor.lineItems and eor.documents contain payer response details.The connected workspace combines that read model with native dialogs for every available action. The remittance surface distinguishes amount billed, payer allowed and reported paid amounts, principal posted to the bill, penalty and interest, total cash received, and remaining balance. Its payment ledger records partial payments, payment references, effective and deposit dates, and EOR source.
Take the next action
Read lifecycle.actions instead of reproducing payer rules in your application. MindBill returns only the actions that make sense for the current bill and explains why an unavailable action is disabled.
rejectedSubmit a new corrected snapshot, or close.accepted / processedTrack the response, or close.denied / partially_paidView EOR, post payment, request Second Bill Review, or close.second_reviewTrack SBR; request IBR when MindBill reports eligibility.paid / closedRead EOR and history; no collection action remains.// Payment received after an EOR.
await mindbill.performBillAction(billId, {
action: "post_payment",
amount: 650,
method: "eft",
depositDate: "2026-09-04",
}, "payment-bill-123-1");
// Close a bill at any stage.
await mindbill.performBillAction(
billId,
{ action: "close", reason: "Resolved outside billing" },
"close-bill-123",
);Correct a rejected bill
Use the resubmit action on the original bill. It preserves the logical bill ID and creates a new immutable submission attempt. Send the full corrected bill and the documents selected for that attempt; this is not a partial update or a new unrelated bill.
// correctedBill is the full, reviewed bill payload.
const response = await fetch(
`https://app.mindbill.org/partner/v2/bills/${billId}/actions`,
{
method: "POST",
headers: {
Authorization: `Bearer ${process.env.MINDBILL_API_KEY}`,
"Content-Type": "application/json",
"Idempotency-Key": "correct-bill-123-attempt-2",
},
body: JSON.stringify({
action: "resubmit",
actorName: authorizedUser.displayName,
reason: "Corrected the rejected claim number",
bill: correctedBill,
documents: selectedBillingDocuments,
}),
},
);
if (!response.ok) throw new Error(`Correction failed: ${response.status}`);This server-side example assumes your application has authenticated authorizedUser, checked their access to billId, and prepared the bill and document payloads. The action endpoint also accepts browser credentials. The connected lifecycle component provides the correction dialog for you.
Show bill history
The connected lifecycle response includes newest-first activity. BillActivityTimeline renders it directly, or accepts the same records from your own webhook-backed store.
In React 0.48.0 and later, submission cards open the selected submission's Bill details; Bill history remains a separate, explicit tab. Custom interfaces can read lifecycle.submissionDetails, matching both attemptId and billId. A submission_snapshot is the captured outgoing detail, bill_record is a labeled legacy fallback, and unavailable means no trustworthy detail exists. Do not replace missing historical data with today's bill or turn unrecorded historical payment amounts into zero.
When retained transmission files exist, each submission detail includes artifacts with opaque IDs, labels, kind, and content type. Keep the lifecycle client configured with the original bill ID and call client.getSubmissionArtifact(attemptId, artifactId) to receive a Blob. The connected component downloads the selected submission's exact electronic bill or attachments, not a packet regenerated from today's records. The equivalent server-key route is GET /partner/v2/bills/{billId}/submissions/{attemptId}/artifacts/{artifactId}, with bills:read.
Second Bill Review before IBR
California payment disputes generally begin with Second Bill Review. If the dispute remains eligible after SBR, the provider may proceed to Independent Bill Review. Medical-legal SBR uses the DWC SBR-1 process and supporting documents.
const { data: secondReview } = await mindbill.createBillReview(
billId,
{
type: "second_review",
reason: "The report satisfies the medical-legal criteria.",
payerClaimControlNumber: "PCCN-88421",
disputedAmount: 2015,
attachmentIds: [reportId, eorId],
},
"create-sbr-bill-123",
);
await mindbill.submitBillReview(
billId,
secondReview.id,
"submit-sbr-bill-123",
);The connected Second Review dialog can correct a selected service line's units, modifiers, and charge for the new submission. Review the charge explicitly: changing units or modifiers does not automatically reprice the bill. For a custom browser UI using @mindbill/browser 0.29.0 or later, submitSecondReview accepts lineItems[].correction with all three absolute values: units, modifiers, and charge. Omit the correction to preserve that line. This lifecycle-action payload differs from the review-record example above; both endpoints accept server or browser credentials.
Team notes and courtesy copies
ConnectedBillLifecycle includes team notes and Forward copy on the current bill. Notes are workspace-only and do not enter the outgoing bill packet. Historical submission views remain read-only. Server actions require bills:write; browser actions require an origin-bound session with bills:act and access to the bill.
The lifecycle response includes notes with id, body, author, createdAt, and pinned. The connected component renders these notes with their author and time by default. Read the canonical bill lifecycle when switching submission attempts, so notes remain part of the bill conversation rather than a host-only copy.
// authenticatedUser comes from your trusted host session.
await mindbill.performBillAction(billId, {
action: "add_note",
note: "Reviewed the corrected claim number with the billing team.",
actorName: authenticatedUser.displayName,
}, "note-bill-123-review-1");
// Reuse the same key when retrying this same note. Reload lifecycle.notes.
// Without actorName the API uses the generic author "Partner team".Forward copy previews a combined PDF containing the mandatory submission cover sheet, the optional CMS-1500, and selected bill documents. The user reviews recipients, message, and packet before confirming. MindBill uses the workspace inbox for sender and reply routing. Forwarding is for the recipient's records: it neither submits the claim nor changes its billing status.
Partners can supply their own case-contact options through the courtesyCopyRecipientOptions prop on ConnectedBillLifecycle, or the getCourtesyCopyRecipientOptions callback on ConnectedBillingWorkspace. These named email suggestions appear in the To/CC chooser; users can also enter an address manually. Suggestions do not grant permission to disclose the packet, trigger a send, or enroll contacts in automatic notifications.
Use events for durable synchronization
Component callbacks keep the current screen responsive. Signed webhooks should update your database in the background. Store the event ID before processing so a retry is harmless.
Verified console members can opt into their own status and aging emails in the developer console's Settings → Notifications. Preferences are separate for each workspace and environment; sandbox previews never send email. Opting in does not send historical catch-up messages. These notices contain no patient or bill details.
{
"id": "evt_0189",
"sequence": "4217",
"type": "bill.denied",
"apiVersion": "2026-08-01",
"createdAt": "2026-08-25T17:42:18Z",
"data": {
"billId": "bill_123",
"balanceDue": 2015,
"reason": "Medical necessity or frequency"
}
}