API reference
REST API
Create and submit workers’ compensation bills, then manage documents, status, payer responses, payments, and reviews through one versioned JSON API.
https://app.mindbill.org/partner/v2Use the same business endpoints from your server or browser to look up reference data, create and submit bills atomically, and perform allowed lifecycle actions. All resources are isolated to the organization attached to the credential.
The downloadable OpenAPI contract describes the shared API and the credentials accepted by each operation.
Conventions
Authentication
Business endpoints accept a server API key or a short-lived browser session as a bearer token. Browser sessions also require the authorized Origin and remain limited by their permissions and bill scope. Session issuance, management sessions, events, and webhook-delivery administration require a server key. See authentication for setup and permission rules.
curl https://app.mindbill.org/partner/v2/bills \
--header "Authorization: Bearer $MINDBILL_API_KEY"Idempotency
For endpoints marked idempotent, send a stable Idempotency-Key on mutations. Reusing a key with the same request safely returns the original result; reusing it with a different request is rejected.
Directories
/claims-administratorsBrowse the payer directory or search administrators and payer choices before a bill exists.
/claims-administrators/{id}Read an administrator's contact information, submission instructions, and payer metadata.
/diagnosis-codesLook up ICD-10-CM codes by code prefix or description.
/postal-codesResolve a US ZIP code into a city and state.
/delivery-previewRead delivery choices and a recommended route before submitting a bill.
/organization/claims-administratorsRead active claims-administrator contacts saved for this organization.
/organization/claims-administratorsSave an organization-specific fax, email, or mail destination.
/organization/claims-administrators/{id}Edit an organization-specific fax, email, or mail destination.
/organization/claims-administrators/{id}Remove a saved destination from future choices.
Bills
/report-autofillExtract review-only bill suggestions from one report PDF without saving or submitting a bill.
/fee-quotes/ca/claimEstimate statutory fees and assess supported same-day coding edits across multiple service lines.
/fee-quotesEstimate a treatment line with optional authorized practice-charge or payer-contract context.
/billsAtomically validate, create, attach the payer packet, and submit an immutable bill snapshot.
/billsList bills belonging to the authenticated organization.
/bills/{billId}Read the complete frozen claim snapshot and payer packet for one bill.
Documents
Reviews
/bills/{billId}/reviewsCreate a Second Bill Review or Independent Bill Review draft with selected evidence.
/bills/{billId}/reviewsList Second Bill Review and Independent Bill Review attempts for a bill.
/bills/{billId}/reviews/{reviewId}Retrieve one review draft or submitted review with its selected evidence.
/bills/{billId}/reviews/{reviewId}/submissionsSubmit a completed SBR or IBR through the bill’s available delivery route.
Lifecycle
/bill-dashboardOrganization-wide page pagination and dashboard filters.
/bill-tasksOrganization-wide task dashboard and waiting queues.
/reports/productivityOrganization-wide report for the date range.
/reports/service-line-itemsOrganization-wide report for the date range.
/bills/{billId}/courtesy-forwardPreview the exact PDF, recipients, and message before sending.
/bills/{billId}/delivery-optionsRead delivery choices for an existing bill.
/bills/{billId}/eors/{docId}Download an original EOR PDF by its document identifier.
/bills/{billId}/ibr-packetDownload the prepared Independent Bill Review packet.
/bills/{billId}/submissionsCompatibility endpoint.
/bills/{billId}/lifecycleRead the immutable submitted bill snapshot, human-readable activity history, current lifecycle, EORs, payments, remittance, and payer contacts.
/bills/{billId}/packetDownload one ordered PDF containing truthful submission proof and timeline, the MC 1500, selected supporting attachments, and the practice W-9 when available.
/sandbox/bills/{billId}/simulateAdvance a submitted synthetic sandbox bill through deterministic accepted, processed, rejected, denied, partial-payment, or paid scenarios.
/bills/{billId}/reviews/{reviewId}/packetFor independent_bill_review reviews only.
/bills/{billId}/statusRead normalized lifecycle state, balances, and the latest event position.
/bills/{billId}/eorRead structured Explanation of Review data and source documents.
/bills/{billId}/actionsClose, post payment, or start a payer review from one state-aware operation.
Platform
/organizationRead the composed profile for the authenticated organization.
/organization/billing-profileRead masked provider and location choices for bill creation.
/organizations/{id}Read the composed profile.
/organization/billing-profileSave profile settings.
/organization/locationsSave profile settings.
/organization/w9Save profile settings.
/organizations/{id}/locationsSave profile settings.
/organizations/{id}/w9Save profile settings.
/organizations/{id}/locationsRead saved locations.
/organizationsCreate or find a managed organization using your stable externalId.
/organization/teamRead existing MindBill accounts and permitted role choices.
/organization/team/{id}Change an eligible existing MindBill account's role or active state.
/eventsRead an ordered cursor-based stream of organization billing changes.
/webhook-deliveriesInspect recent webhook attempts and their delivery outcome.
/browser-sessionsExchange a server API key for a short-lived, organization-bound browser token.
/management-sessionsMint a one-time sign-in URL that opens the hosted MindBill billing workspace for your organization.
/organizations/{id}/billing-profileUpsert practice identity, billing providers, and rendering providers for an authorized organization.
Errors
API errors generally use RFC 9457-style Problem Details. Lookup routes also have endpoint-specific error shapes documented on their reference pages; the diagnosis-code lookup can return an error field with HTTP 200. Use code for program logic and map each errors[].path back to the corresponding form field.
{
"type": "about:blank",
"title": "The request body is invalid.",
"status": 422,
"code": "validation_error",
"detail": "Complete the required bill fields and submit again.",
"errors": [
{ "path": "bill.renderingProvider.taxonomy", "message": "Required" },
{ "path": "bill.diagnoses", "message": "Add at least one ICD-10 code" }
]
}Malformed JSON or an invalid parameter.
Missing, expired, or invalid credential.
The credential lacks the organization, resource, or role permission.
The resource does not exist in the authenticated organization.
Lifecycle conflict or idempotency-key reuse with different input.
The request body, or the total document bytes on a submission, exceeded the size limits.
A document was not a valid PDF, or exceeded the 25 MB per-document limit.
Bill data failed field or submission validation.
Rate limit exceeded; retry with backoff.