Create and submit a bill

Stable report, case, or work-item identifier in your system. Use it to find the bill later.

Select medical-legal billing or professional treatment billing. Professional billing requires treatmentBilling enabled for the organization; otherwise the API returns treatment_billing_not_enabled.

Professional bills may use manual pricing with an explicit charge on every line and no feeContext. This skips ordinary fee-schedule quotes. Anesthesia and drug lines require the verified pricing workflow and cannot use manual mode. Medical-legal bills use automatic pricing.

Your patient identifier. Do not send this together with patient.id.

Patient given name.

Patient middle name or initial.

Patient family name.

Patient date of birth.

Patient Social Security number. Omit to use the claim-form fallback 999999999.

Patient sex or gender value. Omit when unknown.

Patient phone number.

Patient street address.

Patient suite, unit, or secondary address line.

Patient city.

Two-letter state code.

Patient ZIP or ZIP+4 postal code.

Your injury or claim identifier. Do not send this together with claim.id.

Workers’ compensation claim number assigned by the payer or administrator.

California WCAB/EAMS case number when applicable.

Employer name associated with the injury.

Date of injury. For a cumulative injury, use the final injury date and describe the range separately.

Two-letter state code governing the claim. Use CA for automatic California OMFS professional pricing.

Short injury description.

Opaque MindBill payer-directory identifier selected from the claims-administrator directory.

Optional payer-choice key from the claims-administrator search results (payers[].key). Required when the selected administrator needs a payer choice; this is not a clearinghouse payer ID.

Canonical carrier or third-party administrator display name.

Primary date of service for the bill. Fee calculations select sources and rules effective on this date unless a line supplies serviceDate.

End date only for a service that spans multiple dates.

Prior authorization number when the payer supplied one.

Payee identity printed in CMS-1500 boxes 25 and 33. Organization-wide integrations may supply only savedProviderId to resolve a saved billing provider without returning its SSN to the browser. Customer-scoped and bill-scoped credentials cannot use shared saved providers. The fields below are required only for an inline snapshot.

Billing provider or practice name.

Billing provider EIN or SSN.

Billing provider NPI.

Billing provider phone number.

Billing provider street address.

Billing provider suite, unit, or secondary address line.

Billing provider city.

Two-letter state code.

Billing provider ZIP or ZIP+4 postal code.

Clinician identity printed in CMS-1500 box 24J.

Rendering clinician name.

Rendering provider NPI.

NUCC taxonomy code sent with qualifier ZZ and used to identify the provider type for applicable fee rules.

Human-readable specialty.

State professional license number.

Two-letter license state.

Facility address and place-of-service code printed in CMS-1500 box 32.

Human-readable facility name.

CMS place-of-service code. Fee calculations use the actual setting, including facility versus non-facility rates where applicable.

Service location street address.

Service location suite, unit, or secondary address line.

Service location city.

Two-letter state code.

Service location ZIP or ZIP+4 postal code. Fee calculations use the service ZIP to select the applicable geographic locality when required.

At least one ICD-10 diagnosis code.

At least one procedure line.

Procedure or service code, such as ML201 or 99205. This selects the base schedule rule together with the service date and context.

Actual procedure modifiers without hyphens. Modifiers can change pricing or review requirements.

Positive integer unit count used to calculate the extended line amount.

Optional extended billed-charge override in dollars, not a unit price or allowance. For supported professional lines, MindBill uses a matching practice charge or the statutory maximum when omitted. Specialty claim forms can still require a charge.

Treatment line date of service; defaults to service.date. When supplied, this date selects the applicable fee sources for the line.

Optional treatment line end date.

Professional treatment: one-based positions in diagnoses that apply to this procedure. Medical-legal billing uses the shared diagnosis list.

Optional saved RFA item for professional treatment. The server validates the authorization against this bill; linking an item does not establish approval.

Optional clinical and billing facts for fee verification when a service differs from the standard context inferred from the bill or requires specialty details. Explicit context wins over defaults. Unresolved pricing is returned in pricing.status and pricing.warnings rather than treating the charge as an allowance.

Chosen delivery route. Omit to use MindBill routing.

Optional intentional fax, email, or mail destination override.

Complete payer packet included atomically with the submitted bill. Maximum 25 documents, and 45 MB of PDF bytes in total across the submission.

Filename shown in the payer packet.

Document classification such as final_report, proof_of_service, w9, or other.

Base64-encoded PDF bytes. Maximum 25 MB per document measured before encoding. The file must be a real PDF.

Your stable source-document identifier.

Optional PWK01 report-type code. Med-legal components default to J4.

Stable MindBill bill identifier.

Your supplied source-system identifier.

Current native lifecycle state.

Billing rule set used by the bill.

Human-readable MindBill bill number when assigned.

Frozen patient values on this bill.

Frozen claim and payer values, including diagnoses.

Primary service date, optional end date, and authorization number.

Procedure lines with billed charges and fee-calculation results kept separate.

Extended billed charge in dollars. This is not necessarily the expected reimbursement.

Whether the line has a verified saved calculation, only a manual charge, or needs review.

Saved estimated reimbursement in dollars. Null when no verified calculation is available.

Applicable fee-schedule ceiling before a billed-charge cap, in dollars.

Statutory maximum retained separately when a payer contract applies.

Source of the expected reimbursement when calculated.

Structured attention items such as charge_exceeds_schedule_maximum, fee_context_required, or saved_fee_quote_mismatch.

Documents currently included in the payer packet.

Charged, paid, and balance amounts.