Bills API

Create and submit a bill

Atomically validate, create, attach the payer packet, and submit an immutable bill snapshot.

POSThttps://app.mindbill.org/partner/v2/bills

Call once after the user reviews the complete bill form and presses Submit. A failed request creates no public bill.

AuthenticationServer API key or browser session + Origin

Permissions by credentialServer: bills:write · Browser: bills:create

IdempotencyRequired for safe retries

Use this URL with a server API key or a browser session and its exact allowed Origin. Both credentials use the same request and response contract. See the component API inventory for exact paths and SDK methods.

Request body

FieldTypeDescription

bill.externalId

string

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

bill.billingMode

"med_legal" | "professional"

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

Default: "med_legal"

bill.patient.externalId

string

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

bill.patient.firstNameRequired

string

Patient given name.

bill.patient.middleName

string

Patient middle name or initial.

bill.patient.lastNameRequired

string

Patient family name.

bill.patient.dateOfBirthRequired

string

Patient date of birth.

YYYY-MM-DD

bill.patient.ssn

string

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

bill.patient.gender

"M" | "F" | "X"

Patient sex or gender value. Omit when unknown.

bill.patient.phone

string

Patient phone number.

bill.patient.address.line1Required

string

Patient street address.

bill.patient.address.line2

string

Patient suite, unit, or secondary address line.

bill.patient.address.cityRequired

string

Patient city.

bill.patient.address.stateRequired

string

Two-letter state code.

2 characters

bill.patient.address.postalCodeRequired

string

Patient ZIP or ZIP+4 postal code.

bill.claim.externalId

string

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

bill.claim.claimNumberRequired

string

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

bill.claim.adjNumber

string

California WCAB/EAMS case number when applicable.

bill.claim.employerRequired

string

Employer name associated with the injury.

bill.claim.dateOfInjuryRequired

string

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

YYYY-MM-DD

bill.claim.injuryState

string

Two-letter state code governing the claim.

bill.claim.description

string

Short injury description.

bill.claim.claimsAdministrator.idRequired

string

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

bill.claim.claimsAdministrator.payerId

string

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.

bill.claim.claimsAdministrator.nameRequired

string

Canonical carrier or third-party administrator display name.

bill.service.dateRequired

string

Primary date of service for the bill.

YYYY-MM-DD

bill.service.endDate

string | null

End date only for a service that spans multiple dates.

YYYY-MM-DD

bill.service.authorizationNumber

string | null

Prior authorization number when the payer supplied one.

bill.billingProviderRequired

BillingProviderSnapshot | { savedProviderId: string }

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.

bill.billingProvider.nameRequired

string

Billing provider or practice name.

bill.billingProvider.taxIdRequired

string

Billing provider EIN or SSN.

bill.billingProvider.npiRequired

string

Billing provider NPI.

10 digits

bill.billingProvider.phoneRequired

string

Billing provider phone number.

bill.billingProvider.address.line1Required

string

Billing provider street address.

bill.billingProvider.address.line2

string

Billing provider suite, unit, or secondary address line.

bill.billingProvider.address.cityRequired

string

Billing provider city.

bill.billingProvider.address.stateRequired

string

Two-letter state code.

2 characters

bill.billingProvider.address.postalCodeRequired

string

Billing provider ZIP or ZIP+4 postal code.

bill.renderingProviderRequired

RenderingProviderSnapshot

Clinician identity printed in CMS-1500 box 24J.

bill.renderingProvider.nameRequired

string

Rendering clinician name.

bill.renderingProvider.npiRequired

string

Rendering provider NPI.

10 digits

bill.renderingProvider.taxonomyRequired

string

NUCC taxonomy code sent with qualifier ZZ.

10 alphanumeric characters

bill.renderingProvider.specialty

string

Human-readable specialty.

bill.renderingProvider.licenseNumber

string

State professional license number.

bill.renderingProvider.licenseState

string

Two-letter license state.

2 characters

bill.serviceLocationRequired

ServiceLocationSnapshot

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

bill.serviceLocation.name

string

Human-readable facility name.

bill.serviceLocation.placeOfServiceCodeRequired

string

CMS place-of-service code.

2 digits

bill.serviceLocation.address.line1Required

string

Service location street address.

bill.serviceLocation.address.line2

string

Service location suite, unit, or secondary address line.

bill.serviceLocation.address.cityRequired

string

Service location city.

bill.serviceLocation.address.stateRequired

string

Two-letter state code.

2 characters

bill.serviceLocation.address.postalCodeRequired

string

Service location ZIP or ZIP+4 postal code.

bill.diagnosesRequired

string[]

At least one ICD-10 diagnosis code.

1–50 items; professional bills support at most 12

bill.serviceLinesRequired

ServiceLine[]

At least one procedure line.

1–50 items

bill.serviceLines[].codeRequired

string

Procedure or service code, such as ML201 or 99205.

bill.serviceLines[].modifiers

string[]

Procedure modifiers without hyphens.

bill.serviceLines[].units

number

Positive integer unit count.

Default: 1; 1–10,000

bill.serviceLines[].charge

number

Reviewed total charge for this line, not a unit price. Required for professional treatment bills; do not assume a fee quote is available for every service.

> 0

bill.serviceLines[].serviceDate

string

Treatment line date of service; defaults to service.date.

YYYY-MM-DD

bill.serviceLines[].serviceDateEnd

string

Optional treatment line end date.

YYYY-MM-DD

bill.serviceLines[].diagnosisPointers

number[]

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

At most 4 pointers, each 1–12 and referencing a supplied diagnosis

bill.serviceLines[].rfaItemId

string

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

bill.serviceLines[].feeContext

object

Clinical and billing context for server verification of a treatment fee. Code, dates, units, charge, provider/payer identity, and service location are taken from the bill. An unresolved quote returns 422 bill_fee_requires_review. See the California fee guide and OpenAPI for the applicable specialty context.

submission.route

"ebill" | "fax" | "mail" | "email"

Chosen delivery route. Omit to use MindBill routing.

submission.destination

object

Optional intentional fax, email, or mail destination override.

documents[]

BillSubmissionDocument[]

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

documents[].filenameRequired

string

Filename shown in the payer packet.

documents[].documentTypeRequired

BillDocumentType

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

documents[].contentBase64Required

string

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

documents[].externalId

string

Your stable source-document identifier.

documents[].reportTypeCode

string

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

Examples

curl https://app.mindbill.org/partner/v2/bills \
  --request POST \
  --header "Authorization: Bearer $MINDBILL_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: report_9f7a" \
  --data '{
    "bill": {
      "externalId": "report_9f7a",
      "billingMode": "med_legal",
      "patient": {
        "externalId": "patient_42",
        "firstName": "Alex",
        "lastName": "Morgan",
        "dateOfBirth": "1984-05-17",
        "address": {
          "line1": "100 Main St",
          "city": "Fresno",
          "state": "CA",
          "postalCode": "93721"
        }
      },
      "claim": {
        "externalId": "claim_17",
        "claimNumber": "WC-44871",
        "employer": "Example Foods",
        "dateOfInjury": "2026-02-14",
        "claimsAdministrator": {
          "id": "payer_example_01",
          "name": "Example Claims Administrator"
        }
      },
      "service": { "date": "2026-08-26" },
      "billingProvider": {
        "name": "Example Evaluations",
        "taxId": "123456789",
        "npi": "1234567890",
        "phone": "5595550100",
        "address": { "line1": "200 Market St", "city": "Fresno", "state": "CA", "postalCode": "93721" }
      },
      "renderingProvider": {
        "name": "Morgan Chen, MD",
        "npi": "1098765432",
        "taxonomy": "2084P0800X"
      },
      "serviceLocation": {
        "name": "Fresno Exam Office",
        "placeOfServiceCode": "11",
        "address": { "line1": "300 Pine Ave", "city": "Fresno", "state": "CA", "postalCode": "93721" }
      },
      "diagnoses": ["M25.512"],
      "serviceLines": [{ "code": "ML201", "modifiers": ["95"], "units": 1 }]
    },
    "submission": { "route": "ebill" },
    "documents": [{
      "filename": "final-report.pdf",
      "documentType": "final_report",
      "contentBase64": "$FINAL_REPORT_BASE64",
      "externalId": "document_73"
    }]
  }'

import { MindBillClient } from "@mindbill/node";

const mindbill = new MindBillClient({
  apiKey: process.env.MINDBILL_API_KEY!,
});

const bill = await mindbill.createAndSubmitBill({
  bill: {
    externalId: "report_9f7a",
    billingMode: "med_legal",
    patient: {
      externalId: "patient_42",
      firstName: "Alex",
      lastName: "Morgan",
      dateOfBirth: "1984-05-17",
      address: {
        line1: "100 Main St",
        city: "Fresno",
        state: "CA",
        postalCode: "93721",
      },
    },
    claim: {
      externalId: "claim_17",
      claimNumber: "WC-44871",
      employer: "Example Foods",
      dateOfInjury: "2026-02-14",
      claimsAdministrator: {
        id: "payer_example_01",
        name: "Example Claims Administrator",
      },
    },
    service: { date: "2026-08-26" },
    billingProvider: {
      name: "Example Evaluations",
      taxId: "123456789",
      npi: "1234567890",
      phone: "5595550100",
      address: { line1: "200 Market St", city: "Fresno", state: "CA", postalCode: "93721" },
    },
    renderingProvider: {
      name: "Morgan Chen, MD",
      npi: "1098765432",
      taxonomy: "2084P0800X",
    },
    serviceLocation: {
      name: "Fresno Exam Office",
      placeOfServiceCode: "11",
      address: { line1: "300 Pine Ave", city: "Fresno", state: "CA", postalCode: "93721" },
    },
    diagnoses: ["M25.512"],
    serviceLines: [{ code: "ML201", modifiers: ["95"], units: 1 }],
  },
  submission: { route: "ebill" },
  documents: [{
    filename: "final-report.pdf",
    documentType: "final_report",
    contentBase64: finalReportBytes.toString("base64"),
    externalId: "document_73",
  }],
}, "report_9f7a");

Response

201 Created

{
  "id": "bill_01J6Y7F4Q4XK6P3J9G2C8A1B5D",
  "externalId": "report_9f7a",
  "state": "submitted",
  "billingMode": "med_legal",
  "billNumber": 1038,
  "patient": { "firstName": "Alex", "lastName": "Morgan", "address": { "line1": "100 Main St", "city": "Fresno", "state": "CA", "postalCode": "93721" } },
  "claim": { "claimNumber": "WC-44871", "employer": "Example Foods", "dateOfInjury": "2026-02-14", "claimsAdministrator": { "id": "payer_example_01", "name": "Example Claims Administrator" }, "diagnoses": ["M25.512"] },
  "service": { "date": "2026-08-26", "endDate": null, "authorizationNumber": null },
  "billingProvider": { "name": "Example Evaluations", "taxId": "123456789", "npi": "1234567890", "phone": "5595550100", "address": { "line1": "200 Market St", "city": "Fresno", "state": "CA", "postalCode": "93721" } },
  "renderingProvider": { "name": "Morgan Chen, MD", "npi": "1098765432", "taxonomy": "2084P0800X" },
  "serviceLocation": { "name": "Fresno Exam Office", "placeOfServiceCode": "11", "address": { "line1": "300 Pine Ave", "city": "Fresno", "state": "CA", "postalCode": "93721" } },
  "serviceLines": [{ "id": "line_01", "code": "ML201", "modifiers": ["95"], "units": 1, "allowed": 2015 }],
  "documents": [{
    "id": "doc_01J6Y7J2E7D3J5F9Q8K4M6N1P0",
    "externalId": "document_456",
    "filename": "final-report.pdf",
    "documentType": "final_report",
    "source": "partner_api",
    "addedAt": "2026-08-26T18:42:15.000Z",
    "contentUrl": "https://app.mindbill.org/partner/v2/bills/bill_01J6Y7F4Q4XK6P3J9G2C8A1B5D/documents/doc_01J6Y7J2E7D3J5F9Q8K4M6N1P0/content"
  }],
  "amounts": { "charged": 2015, "paid": 0, "balance": 2015 }
}

FieldTypeDescription

idRequired

string

Stable MindBill bill identifier.

externalIdRequired

string | null

Your supplied source-system identifier.

stateRequired

string

Current native lifecycle state.

billingModeRequired

"med_legal" | "professional"

Billing rule set used by the bill.

billNumberRequired

number | null

Human-readable MindBill bill number when assigned.

patientRequired

PatientSnapshot

Frozen patient values on this bill.

claimRequired

ClaimSnapshot

Frozen claim and payer values, including diagnoses.

serviceRequired

object

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

serviceLinesRequired

ServiceLine[]

Procedure lines and calculated allowed amounts.

documentsRequired

BillDocument[]

Documents currently included in the payer packet.

amountsRequired

object

Charged, paid, and balance amounts.