MagicDoorAPI
SupportOpen MagicDoor
Reconciliation items

Generate candidates for an item

Asks MagicDoor to work out fresh suggestions for how to resolve an item. The work happens in the background — the response tells you it has been requested, not what it found. Requires the reconciliations:write permission.

POST
https://services.magicdoor.com/accounting/company-portal/reconciliations/items/{reconciliationItemId}/candidates/generate

Authorization

Authorizationstringrequired
Bearer token — Send your API token in the Authorization header as Bearer <token>. Requests without a valid token are rejected with 401 Unauthorized.

Path parameters

reconciliationItemIdstringrequired

Snowflake id of the reconciliation item.

example: 1830472847398410100

Response

200 · The item with `candidateGeneration.status` set to `pending`, or unchanged when a run was already under way.

idstring

Snowflake id of the reconciliation item.

bankAccountIdstring

The bank account the bank feed entry landed in.

bankFeedEntryIdstring

The 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.

openneedsReviewcompleted
amountnumber

The 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-time

When the bank says the money moved, in the company's timezone.

descriptionstring

The description the bank supplied for the entry.

sourceTypeenum<string>

How the entry reached MagicDoor — a provider feed, a manual entry, or a file import.

plaidyodleemanualpdfImportcsvImportofxImportapiImport
entryStatusenum<string>

active normally; retracted once the bank withdraws the entry. A retracted entry under a resolved item raises a review.

activeretracted
lockedPeriodIdstring

The locked reconciliation period this item belongs to. Absent while it is not locked, and while it is absent the item can still be changed.

candidateCountinteger

How many suggestions are currently on the item, so a list can show a badge without loading them.

candidateGenerationobject

The state of the last suggestion run. Absent when generation has never been asked for.

resolutionobject

How the entry was explained. Absent while the item is open.

reviewobject

An outstanding question about a resolution that is already in place. Absent when there is none.

createdstring · date-time

When the item was created, in the company's timezone.

updatedstring · date-time

When it last changed, in the company's timezone.

metadataobject

Whatever 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.

capabilitiesobject

What 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.

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, or it is locked in a reconciliation period.

Request, then poll

  1. Ask

    Call this endpoint. The item comes back with candidateGeneration.status set to pending.

  2. Poll

    Re-read the item with Get a reconciliation item until candidateGeneration.status becomes ready or failed.

  3. Use them

    On ready, candidates holds up to five suggestions. Accept one with type: "accept", or use it to pre-fill a manual resolve.

Calling it twice is harmless

While a generation is already pending the call returns the item unchanged rather than starting a second run. It only starts a new one once the previous run has finished or has been pending for more than ten minutes.