Post a bank ledger transfer
Records money moving into, out of, or between the company's bank accounts, and posts the transactions behind it. Requires the bank_ledger_transfers:write permission and a company with the company ledger enabled.
Authorization
AuthorizationstringrequiredBody
application/json
Which of outgoing, incoming and offsetAccount you must send is decided entirely by transferType.
transferTypeenum<string>requiredThe kind of movement. It cannot be changed afterwards.
amountnumberrequiredHow much moves, as a positive decimal between 0.01 and 999999999.99. Never send a negative amount to reverse a direction — pick the other transferType.
transferDatestring · date-timeThe date the money moved, read in the company's timezone. Defaults to now.
outgoingobjectThe bank side money leaves. Required for bankToBank and bankWithdrawal; must be omitted for bankDeposit.
incomingobjectThe bank side money arrives in. Required for bankToBank and bankDeposit; must be omitted for bankWithdrawal.
offsetAccountobjectThe non-bank side of the entry. Required for bankDeposit and bankWithdrawal; must be omitted for bankToBank.
propertyIdstringAttribute the movement to a property. Its portfolio is resolved server-side and stamped on the transactions.
paymentMethodenum<string>How the money moved. Defaults to other.
externalTransactionTypeenum<string>Where the movement was seen outside MagicDoor. Defaults to offline.
externalTransactionIdstringThe identifier the external system uses, up to 200 characters.
memostringFree-text note, up to 1000 characters.
referencestringYour own reference, up to 200 characters.
metadataobjectArbitrary string-to-string map stored with the transfer.
Response
200 · The transfer that was posted, with its legs read back from the transactions it created.
idstringSnowflake id of the transfer.
createdstring · date-timeWhen the transfer was recorded, in the company's timezone.
updatedstring · date-timeWhen the transfer was last adjusted, in the company's timezone.
transferDatestring · date-timeThe date the money moved, in the company's timezone. This is the transaction date on the underlying entries.
transferTypeenum<string>What kind of movement this is: bankToBank between two of the company's bank accounts, bankDeposit into one bank account from a non-bank account, bankWithdrawal out of one bank account to a non-bank account. Fixed at creation — an adjustment cannot change it.
amountnumberHow much moved, as a positive decimal. The direction is carried by transferType, never by the sign.
propertyIdstringThe property the movement is attributed to. Absent when it is not attributed to one.
paymentMethodenum<string>How the money moved, read back from the underlying transactions. Absent when the transfer has no linked transactions.
outTransactionIdstringThe out transaction that credits the outgoing bank account's cash. Absent on a bankDeposit.
inTransactionIdstringThe in transaction that debits the incoming bank account's cash. Absent on a bankWithdrawal.
outgoingobjectWhere the money left from, read back from the out transaction. Absent on a bankDeposit.
incomingobjectWhere the money landed, read back from the in transaction. Absent on a bankWithdrawal.
offsetAccountobjectThe non-bank side of a one-legged transfer: what the deposit came from, or what the withdrawal was spent on. Absent on a bankToBank.
memostringFree-text note. Absent when none was set.
referencestringYour own reference, for example a wire confirmation number. Absent when none was set.
metadataobjectArbitrary string-to-string map stored with the transfer. An empty object when nothing was stored.
creatorobjectWho recorded the transfer. Deprecated mirrors of id — propertyManagerId, tenantId, vendorId, ownerId — are also present, whichever matches type.
deletedstring · date-timeWhen the transfer was soft-deleted. These endpoints never return deleted transfers, so it is always absent.
400 · `amount` is not positive or out of range, the wrong combination of `outgoing`, `incoming` and `offsetAccount` was sent for this `transferType`, or `memo`, `reference` or `externalTransactionId` is too long.
401 · The access token is missing, expired, or not for this company.
403 · The caller does not hold the `bank_ledger_transfers:write` permission.
404 · A `bankAccountId` names no bank account in this company, or a chart-of-account id names no account visible to it.
422 · The company does not have the company ledger enabled; a bank account is missing its linked cash chart-of-account entry; or the two bank accounts mix a company operating account with a property trust account, which needs a company ledger transfer instead.
transferType | Send | What is posted |
|---|---|---|
bankToBank | outgoing and incoming, no offsetAccount | Two linked transactions: an out on the outgoing bank account's cash account and an in on the incoming one. Cash falls on the outgoing side and rises on the incoming side by amount. |
bankDeposit | incoming and offsetAccount, no outgoing | One in transaction that raises the incoming bank account's cash by amount. offsetAccount carries the other half of the entry. |
bankWithdrawal | outgoing and offsetAccount, no incoming | One out transaction that lowers the outgoing bank account's cash by amount. offsetAccount carries the other half of the entry. |
A bankToBank transfer cannot move money between a company operating account (companyAccount: true) and a property trust account (companyAccount: false). That crossing is a company ledger transfer, not a bank ledger transfer.