Resolve a reconciliation item
Explains a bank feed entry, in one of five ways chosen by the body's type. Requires the reconciliations:write permission.
Authorization
AuthorizationstringrequiredPath parameters
reconciliationItemIdstringrequiredSnowflake id of the reconciliation item.
Body
application/json
The body is one of five shapes, picked by type. Each shape rejects any field it does not define, so you cannot mix accept with the manual fields. An item can only be resolved once — to change your mind, rematch it first.
typeenum<string>requiredWhich resolution shape the rest of the body follows.
candidateIdstringaccept only, and required there: the suggestion to take exactly as it stands. Nothing else may be sent alongside it.
transactionIdsstring[]match only: the existing transactions that explain this bank entry.
identityenum<string>settle: which kind of bill is being paid — vendorBill is the only supported value. post: which kind of transaction to create, one of bankLedgerTransfer, leaseCharge, leaseDeposit, ownerDistribution or ownerContribution. Required in both.
targetsTarget[]settle only, and required there: the bills to pay and how much goes to each. The amounts must add up to the absolute value of the bank entry's amount.
chartOfAccountIdstringsettle: required — the cash asset account the payment comes out of. post: optional — the offset account, where the chosen identity uses one.
cashChartOfAccountIdstringpost only: the cash asset account, where the chosen identity uses one.
propertyIdstringpost only: the property, where the chosen identity uses one.
portfolioIdstringpost only: the portfolio, where the chosen identity uses one.
leaseIdstringpost only: the lease, for a leaseCharge or leaseDeposit posting.
tenantIdstringpost only: the tenant, for a leaseCharge or leaseDeposit posting.
targetChargeIdsstring[]post only: the specific lease charges to pay, for a leaseCharge posting.
targetDepositIdsstring[]post only: the specific lease deposits to pay, for a leaseDeposit posting.
ownerIdstringpost only: the owner, for an ownerDistribution or ownerContribution posting.
ownerTransferTargetsTarget[]post only: how the amount splits across properties, for an ownerDistribution or ownerContribution posting.
reasonenum<string>ignore only, and required there: why the entry needs no record. sourceRemoved and bankAccountDeleted are reserved for MagicDoor's own cleanup and are rejected here.
explanationstringignore only: free-text explanation, up to 1000 characters.
memostringsettle and post: memo for the transaction that gets created, up to 1000 characters.
Response
200 · The item after the resolution, read back in full.
idstringSnowflake id of the reconciliation item.
bankAccountIdstringThe bank account the bank feed entry landed in.
bankFeedEntryIdstringThe bank feed entry this item is about. One item exists per entry.
statusenum<string>Derived, not stored: open when there is no resolution, needsReview when there is one but something underneath it changed, completed when there is one and nothing is outstanding.
amountnumberThe amount the bank reported, as a decimal. Signed, unlike almost every other amount in this API: positive means money arriving in the bank account, negative means money leaving it.
occurredstring · date-timeWhen the bank says the money moved, in the company's timezone.
descriptionstringThe description the bank supplied for the entry.
sourceTypeenum<string>How the entry reached MagicDoor — a provider feed, a manual entry, or a file import.
entryStatusenum<string>active normally; retracted once the bank withdraws the entry. A retracted entry under a resolved item raises a review.
lockedPeriodIdstringThe locked reconciliation period this item belongs to. Absent while it is not locked, and while it is absent the item can still be changed.
candidateCountintegerHow many suggestions are currently on the item, so a list can show a badge without loading them.
candidateGenerationobjectThe state of the last suggestion run. Absent when generation has never been asked for.
resolutionobjectHow the entry was explained. Absent while the item is open.
reviewobjectAn outstanding question about a resolution that is already in place. Absent when there is none.
createdstring · date-timeWhen the item was created, in the company's timezone.
updatedstring · date-timeWhen it last changed, in the company's timezone.
metadataobjectWhatever extra key-value pairs the feed provider attached to the entry. Provider-specific; treat the keys as opaque.
candidatesCandidate[]Current suggestions, at most five. They are disposable, not history: regenerating replaces the whole set, and resolving, invalidating or raising a review clears it. Accepting one keeps only that one, for as long as its resolution stands.
transactionLinksLink[]The transactions the resolution ties this bank entry to, each with a frozen copy of the transaction at the moment it was linked. Comparing that copy with the live transaction is what raises a review.
capabilitiesobjectWhat the item will currently accept. It is advisory — meant for greying out buttons and explaining why — and is not the authorization check. The endpoints enforce their own rules.
chartOfAccountsChartOfAccount[]The accounts referenced anywhere in this payload, resolved for display.
transactionsTransaction[]The transactions referenced by candidates and links, resolved so you do not have to fetch them one by one.
vendorBillsVendorBill[]The vendor bills referenced by the current settling candidates, resolved for display.
portfoliosReference[]Id-to-name pairs for every portfolio mentioned anywhere in this payload, so you do not have to look them up.
propertiesReference[]Id-to-name pairs for every property mentioned anywhere in this payload, so you do not have to look them up.
leasesReference[]Id-to-name pairs for every lease mentioned anywhere in this payload, so you do not have to look them up.
tenantsReference[]Id-to-name pairs for every tenant mentioned anywhere in this payload, so you do not have to look them up.
ownersReference[]Id-to-name pairs for every owner mentioned anywhere in this payload, so you do not have to look them up.
400 · The body does not match its `type` — a required field is missing, an amount is out of range, or a field that shape does not define was sent.
401 · The access token is missing, expired, or not for this company.
403 · The caller does not hold the `reconciliations:write` permission.
404 · No reconciliation item with this id belongs to the caller's company.
422 · The item already has a resolution; it is locked in a period; its bank feed entry is missing, retracted, or on another bank account; or `reason` is `sourceRemoved` or `bankAccountDeleted`, which are reserved for MagicDoor's own cleanup. The `detail` says which.
type | Use it when | What it does |
|---|---|---|
accept | One of the suggestions on the item is right as it stands. | Applies that candidate exactly. Check its canAccept first — an incomplete candidate cannot be accepted. |
match | The money is already in the books as one or more transactions. | Links the bank entry to those transactions. No new transaction is created. |
settle | Money went out to pay vendor bills. | Creates a payment transaction and allocates it across the bills you name. Only available on a negative amount. |
post | The money is not in the books at all yet. | Creates the transaction the chosen identity describes, and links it. |
ignore | MagicDoor should not record this at all. | Marks it explained with a reason and creates nothing. |
An item that already has a resolution rejects a second one, and an item locked into a reconciliation period rejects all of them. Use Rematch to clear a resolution and start again.