Sign in

Bills API

Save a bill draft

Save a treatment bill as entered so far, which may be incomplete, without validating or sending it.

POSThttps://app.mindbill.org/partner/v2/bill-drafts

Call when the biller presses Save draft. Store the returned id and revision with your visit so the bill can be resumed, edited, or submitted later.

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.

Request body

FieldTypeDescription
externalId
string

Your stable reference for this draft, such as a visit ID. Unique per integration, organization, and environment; reuse returns 409 external_id_owned.

1–255 characters
billRequired
object

BillCreate input as entered so far: any subset of the create-bill bill object. Existing patient.id and claim.id values must belong to the organization.

Up to 256 KB
encounter
BillDraftEncounter

Saved IDs used to price the draft with POST /fee-quotes/encounter.

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

Server API key
curl 'https://app.mindbill.org/partner/v2/bill-drafts' \
  --request POST \
  --header "Authorization: Bearer $MINDBILL_API_KEY" \
  --header 'Idempotency-Key: visit_2026_10_08_example-draft' \
  --header 'Content-Type: application/json' \
  --data '{
  "externalId": "visit_2026_10_08_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
        ]
      }
    ]
  },
  "encounter": {
    "renderingProviderId": "rp_example",
    "placeOfServiceId": "loc_example",
    "claimId": "clm_example"
  }
}'
Browser session
curl 'https://app.mindbill.org/partner/v2/bill-drafts' \
  --request POST \
  --header "Authorization: Bearer $MINDBILL_BROWSER_TOKEN" \
  --header 'Origin: https://your-app.example' \
  --header 'Idempotency-Key: visit_2026_10_08_example-draft' \
  --header 'Content-Type: application/json' \
  --data '{
  "externalId": "visit_2026_10_08_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
        ]
      }
    ]
  },
  "encounter": {
    "renderingProviderId": "rp_example",
    "placeOfServiceId": "loc_example",
    "claimId": "clm_example"
  }
}'

Response

201 Created

Response
{
  "data": {
    "id": "billdraft_example",
    "externalId": "visit_2026_10_08_example",
    "status": "draft",
    "revision": 1,
    "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
          ]
        }
      ]
    },
    "encounter": {
      "renderingProviderId": "rp_example",
      "placeOfServiceId": "loc_example",
      "claimId": "clm_example"
    },
    "serviceLineCount": 1,
    "submittedBillId": null,
    "createdAt": "2026-10-08T17:02:11.000Z",
    "updatedAt": "2026-10-08T17:02:11.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.