Sign in

Lifecycle API

Perform a bill action

Close, post payment, or start a payer review from one state-aware operation.

POSThttps://app.mindbill.org/partner/v2/bills/{billId}/actions

Available actions depend on bill state. The React and Angular lifecycle components already render only valid actions.

AuthenticationServer API key or browser session + Origin
Permissions by credentialServer: bills:write (payments:write for post_payment) · Browser: bills:act
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.

Path parameters

FieldTypeDescription
billIdRequired
string

The MindBill bill identifier returned after atomic submission.

Request body

FieldTypeDescription
actionRequired
"close" | "post_payment" | "second_review"

Lifecycle action to perform.

reason
string

Required for close and second_review.

amount
number

Payment amount for post_payment.

method
"check" | "eft"

Payment method for post_payment.

checkNumber
string

Optional check number.

depositDate
string

Required payment deposit date.

YYYY-MM-DD
payerClaimControlNumber
string

Required payer claim control number for second_review.

disputedAmount
number

Amount disputed in the second review.

attachmentIds
string[]

Supporting document IDs intentionally included in the second review.

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

Optional second-review delivery override.

Examples

Post a payment
curl https://app.mindbill.org/partner/v2/bills/$BILL_ID/actions \
  --request POST \
  --header "Authorization: Bearer $MINDBILL_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: payment_check_4811505" \
  --data '{
    "action": "post_payment",
    "amount": 1600,
    "method": "check",
    "checkNumber": "4811505",
    "depositDate": "2026-08-29"
  }'

Response

200 OK

Response
{ "ok": true, "data": { "amount": 1600, "balanceDue": 415 } }
FieldTypeDescription
okRequired
true

Action accepted.

dataRequired
object | null

Action-specific result.