Client Group & Status API — update guide

This guide describes how to manage a resident’s client group (facility) flow when resident is already admitted in the facility.

NOTE: This guide is not applicable to manage resident absences.

Update client group and status (ACR Clinical)

  1. Get the residents current group — GET …/api/Clients/Group/{clientID}/{bUID}/{groupID}.
  2. Apply the user’s changes on the client-group body (businessUnitStatusID, startDateUtc, reasons, comments).
  3. Save the client group — PUT …/api/Clients/Group/{clientID}/{bUID}/{groupID} (optional /{validateOnly}). The path ids overwrite the body’s ids. Successful save returns 200. If status or dates changed, a new status-history row is created and overlapping rows are merged.
  4. Initialize a group-status — this api endpoint provides the sample data model for next POST request GET …/api/Clients/GroupStatus.
  5. Apply the user’s changes on the client group-status body (businessUnitStatusID, startDateUtc, statusReason, statusReason2, statusReason3).
  6. Save the client group-status — POST …/api/Clients/GroupStatus (optional /{validateOnly}).

Update client group and status (ACR finance)

  1. Get the residents current group — GET …/api/Clients/Group/{clientID}/{bUID}/{groupID}.
  2. Apply the user’s changes on the client-group body (businessUnitStatusID, startDateUtc, reasons, comments).
  3. Finance residents need additional data fields noticeDate, refundDueDate that apply only when the resident holds a refundable accommodation deposit (RAD) with a positive balance.

    Load residents RAD(s) — GET …/api/Deposits/Deposit?depositBalanceMin=0.01&entities={clientID}&isRefundable=true. If the result contains at least one deposit then GoTo section Notice date and refund due date (RAD) to calculate noticeDate and refundDueDate, else follow the below steps.

  4. Save the client group — PUT …/api/Clients/Group/{clientID}/{bUID}/{groupID} (optional /{validateOnly}). The path ids overwrite the body’s ids. Successful save returns 200. If status or dates changed, a new status-history row is created and overlapping rows are merged.
  5. Initialize a group-status — this api endpoint provides the sample data model for next POST request GET …/api/Clients/GroupStatus.
  6. Apply the user’s changes on the client group-status body (businessUnitStatusID, startDateUtc, statusReason, statusReason2, statusReason3).
  7. Save the client group-status — POST …/api/Clients/GroupStatus (optional /{validateOnly}).
  8. If the new status is a departure type (Transferred, Discharged, or Deceased) — after the successful save, call the departure invoice batch endpoint if calculateWeekEndingDate returned a non-null week-ending date for the resident's client orders. See Departure invoice batch (RMRV) for the full sequence.

Same validate-only behaviour as create: path segment true validates and returns 200 with an empty body; omitted or false saves.

Notice date and refund due date (RAD) (ACR finance)

noticeDate and refundDueDate are separation-interest fields that apply only when the resident holds a refundable accommodation deposit (RAD) with a positive balance. Integrations should check for refundable deposits before displaying or submitting these fields, then calculate their defaults using the rules below.

Status type Field Required? Notes
Discharged (700) noticeDate Yes Date the resident gave notice of departure. Must come on or before startDateUtc.
Deceased (800) noticeDate No Date probate was received. Must come on or after startDateUtc.

For any other departure type (Transferred, and so on) or when no refundable deposits exist, (send null or exclude noticeDate and refundDueDate entirely).

Default calculation rules (Discharged)
Group Status Condition noticeDate default refundDueDate default
POST noticeDate is not yet set Set to startDateUtc (same as departure date) startDateUtc + 14 days
PUT noticeDate is already set, and startDateUtc − noticeDate > 14 days Leave unchanged Set to startDateUtc
PUT noticeDate is already set, and startDateUtc − noticeDate ≤ 14 days Leave unchanged noticeDate + 14 days

In plain terms: the refund deadline is whichever is later — 14 days after notice, or the departure date itself.

Default calculation rules (Deceased)
Group Status Condition noticeDate (probate date) refundDueDate default
POST noticeDate is not set Leave as null null
PUT noticeDate is set Leave unchanged (user-provided) noticeDate + 14 days
Date validation
  • Discharged — if noticeDate is after startDateUtc the product rejects the save with a validation error ("Notice Date must come before Start Date"). Check this constraint before posting.
  • Deceased — if noticeDate (probate date) is before startDateUtc the product rejects the save ("Probate Received Date must come after Start Date").
  • Recalculate refundDueDate whenever startDateUtc or noticeDate changes.

next Save the client group.

Departure invoice batch (ACR finance)

ACR finance tenants , saving a departure status (Transferred, Discharged, or Deceased) triggers an asynchronous departure invoice generation batch. The product handles this automatically after a successful group-status save.

Steps to trigger invoice batch
  1. Fetch the resident's client orders for the business unit: GET …/api/ClientOrders?clientID={clientID}&businessUnits={buid}. Collect the unique buid values (departureBusinessUnitIDs) and all clientOrderID values (clientOrderIDs).
  2. GET …/api/calculateWeekEndingDate with clientOrderIDs, businessUnitID, stopDate = startDateUtc (the departure date), and groupStatus = statusName.
  3. POST …/api/InvoiceBatchProcess(departureBusinessUnitIDs, clientOrderIDs, weekEndingDate, startDateUtc). 
    {
  "businessUnits": departureBusinessUnitIDs,
  "clientOrderIDs": clientOrderIDs,
  "weekEndingDate": weekEndingDate,
  "departureStopDate": startDateUtc{client-group-status.startDateUtc},
  "generationType": 1,
  "batchType": 3
}