Deposits API — integration guide

This guide describes how an external system (for example a finance or ERP system) records a deposit in AlayaCare Residential and how it adjusts a deposit that already exists. A deposit is money held against a resident, such as a refundable accommodation deposit (RAD) or an unapplied payment.

Request and response models are published on your tenant’s API Help pages, for example https://residential.alayacare.com.au/api/Help (replace the host with yours).

Table of Contents

Overview

Purpose Request Body Success response
Get an empty deposit to fill in GET …/api/Deposits/Deposit/Initialize None 200 OK with a DepositDTO
Create a deposit and its journals POST …/api/Deposits/Deposit DepositDTO 201 Created
Increase or decrease an existing deposit POST …/api/Deposits/Deposit/postAdjustment DepositAdjustmentDTO 200 OK
  • Requests and responses use application/json. Enumerations are sent as their numeric values.
  • Authenticate as described on the home page. Create requires write access to client deposits, and the business unit (buid) must be one the caller can access.
  • Both operations post double-entry journals. Journal types and transaction types referenced below are listed on the Journal Types and Transaction Types pages.
  • Both operations are only allowed in an open posting period.

Create a deposit — POST Deposits/Deposit

POST …/api/Deposits/Deposit creates the deposit record and generates the matching double-entry journal atomically. Use it to record a payment received for a resident, including a RAD payment sent from an external finance system.

  • The body is a DepositDTO. depositID must be 0 or omitted; any other value is rejected with 400 Bad Request.
  • On success the service returns 201 Created with an empty body. The Location header ends with the new depositID.
  • Add /true to the path (POST …/api/Deposits/Deposit/true) to validate only. The request is checked against the field rules below and returns 200 OK without saving anything. The posting-period check is applied only when the deposit is actually saved.
Initialize a deposit — GET Deposits/Deposit/Initialize

GET …/api/Deposits/Deposit/Initialize returns an empty deposit that you can fill in and send to POST Deposits/Deposit. It is optional, and is a convenient way to get the exact shape of the DepositDTO on your tenant.

  • There are no parameters. Nothing is saved, and the response is not pre-filled for a resident, funder or business unit, so you still need to set the fields listed below.
  • Returns 200 OK. Requires write access to client deposits.
  • The defaults in the response:
Field Default
depositID 0 (leave as 0 when creating)
buid, entityID, clientOrderID, funderID, depositTransactionTypeID, paymentTransactionTypeID 0 — must be set
groupID, paymentMethod, retainedAmount, directDebitProcessingDate null
depositDate 0001-01-01T00:00:00 — must be set
depositAmount, depositBalance 0 — must be set
isRefundable, isSettleableToInvoice false
type 1 (Deposit)
depositStatus 1 (Draft) — the service sets it to Posted when the deposit is created
Request fields

Key fields required to represent a deposit such as a RAD payment:

Field Type Notes
buid integer Business unit ID. Access to the business unit is enforced.
entityID integer Resident (client) ID.
funderID integer Required for GL code generation, for deposit type validation (accommodation funder check), and for the funder rule lookup.
clientOrderID integer Required for journal item creation, and for the client order billing rate splits made when a refundable deposit is created.
groupID integer Required to resolve funderRuleID. The service looks up the funder rule from groupID + funderID (and the business unit) that is active on depositDate; a group-specific rule is preferred over the standard rule. funderRuleID is left empty if groupID is omitted or no rule matches.
depositDate date-time Must fall within an open posting period. It is also used as the journal item date.
depositAmount decimal (18,2) Must be >= 0.
depositBalance decimal (18,2) Must be >= 0 and <= depositAmount. For a new, unspent deposit this equals depositAmount.
depositTransactionTypeID integer Drives the DP journal item and its GL code. Must reference a configured transaction type.
paymentTransactionTypeID integer Drives the PM journal item and its GL code.
isRefundable boolean Must be true for a RAD (accommodation deposit).
type integer (DepositType) 1 = Deposit (default) or 3 = IngoingContribution, depending on the business unit type. IngoingContribution is only accepted for an accommodation funder in a retirement village (RV) business unit.

Optional fields

Field Notes
paymentMethod PaymentMethod numeric value: 10 Cash, 20 Cheque, 30 CreditCard, 40 DirectDebit, 50 EFT. Drives the conditional fields below.
comments Free-text comment.
payeeName, payeeAddress Name and address of the payee, carried onto the journal items.
retainedAmount decimal (18,2). Accommodation deposits only (isRefundable = true). Must be > 0 and <= depositAmount.
isSettleableToInvoice Defaults to false. Set to true if the deposit balance can be settled to invoices.

Other fields in the model (for example created, lastUpdated, refunded, receiptNumber, journalItemID) are populated by the service and returned when you read a deposit. You do not need to send them. depositStatus is set to Posted by the service.

Field size limits

These limits apply to the create and adjust requests.

Fields Limit
depositAmount, depositBalance, retainedAmount, adjustmentAmount Currency amounts are decimal (18,2): up to 18 digits in total, of which 2 are decimal places (so up to 16 digits before the decimal point). Send at most 2 decimal places. For an adjustment, the resulting deposit amount and balance must also fit within this size.
comments (create and adjust), chequeNumber, bankName, bankBranch, payeeName, payeeAddress No maximum length is enforced by the API or the database; these are stored as unlimited text.
Conditionally required fields
Condition Additional required fields
paymentMethod = Cheque (20) chequeNumber, bankName, bankBranch
paymentMethod = DirectDebit (40) directDebitProcessingDate — must not be in the past for a new deposit.
paymentMethod is anything other than Cheque chequeNumber, bankName and bankBranch must be empty.
What the service creates
  • A deposit record. The status is set to Posted (depositStatus = 2) once the journals have been generated.
  • A journal of type New Deposit (journal type ID 1), posted.
  • Two linked journal items on that journal, each pointing at the other through referenceJournalItemID:
Journal item Transaction type Amount Notes
Deposit side depositTransactionTypeID (code DP) -depositAmount GL code generated from the deposit transaction type.
Payment side paymentTransactionTypeID (code PM) +depositAmount A receipt number is generated for this item.

For a refundable deposit, the client order billing rates are also split from depositDate once the deposit is saved.

To see the journal items later, read the deposit with GET …/api/Deposits/Deposit (using includeExtraInfo=true) and use the journalItemID and receiptNumber returned for the PM item.

Example request (RAD)
POST /api/Deposits/Deposit
Content-Type: application/json

{
  "buid": 101,
  "entityID": 5532,
  "funderID": 87,
  "clientOrderID": 9120,
  "groupID": 14,
  "depositDate": "2026-10-29T00:00:00",
  "depositAmount": 350000.00,
  "depositBalance": 350000.00,
  "depositTransactionTypeID": 4,
  "paymentTransactionTypeID": 5,
  "isRefundable": true,
  "type": 1,
  "paymentMethod": 40,
  "directDebitProcessingDate": "2026-10-30T00:00:00",
  "payeeName": "Jane Citizen",
  "comments": "RAD payment received"
}

HTTP/1.1 201 Created
Location: https://{host}/api/Deposits/Deposit/48213

IDs shown are illustrative. Use the funder, group, client order and transaction type IDs from your organization; 4 (DP) and 5 (PM) are the built-in Deposit and Payment Made types.

Adjust a deposit — POST Deposits/Deposit/postAdjustment

POST …/api/Deposits/Deposit/postAdjustment increases or decreases an existing deposit. Each call inserts one new journal and two journal items, and updates the deposit’s amount and balance.

  • The body is a DepositAdjustmentDTO (not a journal). The service builds the journal and journal items for you.
  • On success the service returns 200 OK and echoes the request body back unchanged.
  • There is no validate-only option. Each successful call posts immediately, so do not retry a call that succeeded; send a new adjustment with the opposite sign to reverse it.
Request fields
Field Type Required Notes
depositID integer Yes The deposit to adjust. Must be greater than 0 and must exist.
adjustmentAmount decimal (18,2) Yes Signed amount added to both the deposit amount and the deposit balance. Positive increases the deposit; negative decreases it. The resulting depositAmount and depositBalance must each stay at or above 0.
transactionDate date-time Yes Must fall within an open posting period. Used as the journal item date and as the deposit’s balance-last-updated date.
comments string Yes Reason for the adjustment. Copied to both journal items. See field size limits.
What the service creates
  • A journal of type Finance Adjustments (journal type ID 10) with the description Deposit Adjustment, linked to the deposit, and posted.
  • Two linked journal items, built from the deposit’s own transaction types, so no transaction types are sent in the request:
Journal item Transaction type Amount
Deposit side The deposit’s depositTransactionTypeID (DP) -adjustmentAmount
Payment side The deposit’s paymentTransactionTypeID (PM) +adjustmentAmount
  • Both items copy the deposit’s business unit, resident, client order, funder and group, and have a GL code generated from their transaction type. The GL code rule must be configured on both transaction types, otherwise the call fails.
  • The deposit’s depositAmount and depositBalance are both changed by adjustmentAmount.

The adjustment does not change any invoices.

Example request
POST /api/Deposits/Deposit/postAdjustment
Content-Type: application/json

{
  "depositID": 48213,
  "adjustmentAmount": -1500.00,
  "transactionDate": "2026-10-29T00:00:00",
  "comments": "Correction to RAD amount received"
}

HTTP/1.1 200 OK

Errors

Operation Cause
Create Body missing, or depositID is not 0 (400).
Create Field rules above are broken: negative amount or balance, balance above amount, missing cheque or direct debit fields, retainedAmount out of range or on a non-refundable deposit, IngoingContribution on an unsupported business unit or funder.
Create / Adjust The posting date (depositDate / transactionDate) is in a closed posting period.
Adjust Body missing (400); depositID missing or not found; transactionDate or comments missing.
Adjust The adjustment would make the deposit amount or balance negative.
Adjust GL codes have not been configured on the deposit’s deposit or payment transaction type.