Bills API

Replace a bill draft

Replace the saved bill (and optionally its pricing IDs) at the draft's current revision.

PATCHhttps://app.mindbill.org/partner/v2/bill-drafts/{draftId}

Call on each later Save draft. Send the complete bill as entered; it replaces the saved bill rather than merging with it.

AuthenticationServer API key or browser session + Origin

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

IdempotencyRequired for safe retries

Organization capabilitytreatmentBilling must be enabled

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.

Path parameters

FieldTypeDescription

draftIdRequired

string

Bill draft identifier returned when the draft was saved.

1–255 characters

Request body

FieldTypeDescription

expectedRevisionRequired

integer

The draft's current revision from your last read or save.

≥ 1

billRequired

object

The complete bill input as entered so far. Replaces the saved bill.

Up to 256 KB

encounter

BillDraftEncounter | null

Replaces the saved pricing IDs. Omit to keep them; send null to clear them.

encounter.renderingProviderId

string

Saved rendering provider used to price the visit with POST /fee-quotes/encounter.

encounter.placeOfServiceId

string

Saved service location used for pricing.

encounter.billingProviderId

string

Saved billing provider; the organization default applies when omitted.

encounter.claimId

string

Saved claim whose claims administrator and prior therapy visits apply to pricing.

Examples

curl 'https://app.mindbill.org/partner/v2/bill-drafts/billdraft_example' \
  --request PATCH \
  --header "Authorization: Bearer $MINDBILL_API_KEY" \
  --header 'Idempotency-Key: billdraft_example-rev-1' \
  --header 'Content-Type: application/json' \
  --data '{
  "expectedRevision": 1,
  "bill": {
    "billingMode": "professional",
    "claim": {
      "id": "clm_example"
    },
    "patient": {
      "id": "pat_example"
    },
    "service": {
      "date": "2026-10-08"
    },
    "diagnoses": [
      "M54.50"
    ],
    "serviceLines": [
      {
        "code": "99213",
        "units": 1,
        "charge": 150,
        "diagnosisPointers": [
          1
        ]
      },
      {
        "code": "97110",
        "units": 2,
        "charge": 120,
        "diagnosisPointers": [
          1
        ]
      }
    ]
  }
}'

curl 'https://app.mindbill.org/partner/v2/bill-drafts/billdraft_example' \
  --request PATCH \
  --header "Authorization: Bearer $MINDBILL_BROWSER_TOKEN" \
  --header 'Origin: https://your-app.example' \
  --header 'Idempotency-Key: billdraft_example-rev-1' \
  --header 'Content-Type: application/json' \
  --data '{
  "expectedRevision": 1,
  "bill": {
    "billingMode": "professional",
    "claim": {
      "id": "clm_example"
    },
    "patient": {
      "id": "pat_example"
    },
    "service": {
      "date": "2026-10-08"
    },
    "diagnoses": [
      "M54.50"
    ],
    "serviceLines": [
      {
        "code": "99213",
        "units": 1,
        "charge": 150,
        "diagnosisPointers": [
          1
        ]
      },
      {
        "code": "97110",
        "units": 2,
        "charge": 120,
        "diagnosisPointers": [
          1
        ]
      }
    ]
  }
}'

Response

200 OK

{
  "data": {
    "id": "billdraft_example",
    "externalId": "visit_2026_10_08_example",
    "status": "draft",
    "revision": 2,
    "claimId": "clm_example",
    "patientId": "pat_example",
    "bill": {
      "billingMode": "professional",
      "claim": {
        "id": "clm_example"
      },
      "patient": {
        "id": "pat_example"
      },
      "service": {
        "date": "2026-10-08"
      },
      "diagnoses": [
        "M54.50"
      ],
      "serviceLines": [
        {
          "code": "99213",
          "units": 1,
          "charge": 150,
          "diagnosisPointers": [
            1
          ]
        },
        {
          "code": "97110",
          "units": 2,
          "charge": 120,
          "diagnosisPointers": [
            1
          ]
        }
      ]
    },
    "encounter": {
      "renderingProviderId": "rp_example",
      "placeOfServiceId": "loc_example",
      "claimId": "clm_example"
    },
    "serviceLineCount": 2,
    "submittedBillId": null,
    "createdAt": "2026-10-08T17:02:11.000Z",
    "updatedAt": "2026-10-08T17:20:45.000Z",
    "submittedAt": null
  }
}

FieldTypeDescription

data.idRequired

string

Stable draft identifier.

data.externalIdRequired

string | null

Your reference supplied when the draft was created.

data.statusRequired

"draft" | "submitting" | "submitted"

draft is editable. submitting means a POST /bills holds it. submitted is final and carries submittedBillId.

data.revisionRequired

integer

Current revision. Send it as expectedRevision to update or delete, and as draft.revision to submit.

data.claimId / data.patientId

string | null

Existing claim and patient IDs referenced by the saved bill, when present.

data.billRequired

object

The bill input exactly as saved. It may be incomplete.

data.encounter

BillDraftEncounter | null

Saved IDs used to price the draft.

data.serviceLineCount

integer

Number of saved service lines.

data.submittedBillId

string | null

The bill created from this draft once submitted.

data.createdAt / data.updatedAtRequired

string

ISO 8601 timestamps.

data.submittedAt

string | null

When the draft became submitted.