Bank feeds

Exchange a public token

Turns the public token the provider's widget produced into a stored bank feed connection, and links each feed account to the MagicDoor bank account it matches. Requires the reconciliations:write permission.

POST

https://services.magicdoor.com/accounting/company-portal/bank-feeds/public-token/exchange

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.

Body

application/json

publicTokenstringrequired

The token the provider's link widget handed your front end, up to 256 characters. An opaque provider-issued value; MagicDoor passes it straight back to the provider.

example: public-production-2b7e1f04-3a9c-4d61-8e2f-5c4b3a2d1e0f

Response

200 · The stored connection, the accounts that were linked, and the outcome for every account the bank exposed.

connectionobject

The bank feed connection that was created.

connectedAccountsAccount[]

The accounts that were successfully linked to a MagicDoor bank account.

accountMatchesMatch[]

One row for every account the bank exposed, matched or not.

400 · `publicToken` is missing or longer than 256 characters.

401 · The access token is missing, expired, or not for this company.

403 · The caller does not hold the `reconciliations:write` permission.

422 · None of the accounts behind the token could be matched to a company bank account. The problem detail carries `accountMatches` explaining each one.

How linking a bank works

Ask MagicDoor for a link token
Call Create a link token. You get a short-lived linkToken.
Run the provider's flow in the browser
Hand the linkToken to the provider's own link widget. The property manager picks their bank and signs in there. MagicDoor never sees the credentials.
Exchange what the widget gives you
The widget hands your front end a public token. Post it to Exchange a public token and MagicDoor creates the connection and links the accounts it can match.

How accounts are matched

MagicDoor tries to pair each account the bank exposes with one of the company's own bank accounts. Only accounts whose subtype is checking or savings are considered, only company bank accounts that are active and have both a routing number and an account number can be matched to, and the bank must supply usable routing and account numbers of its own. The outcome per account is in matchStatus.

`matchStatus`	Meaning
`Matched`	Paired with exactly one company bank account — `bankAccountId` and `bankAccountName` name it, and the feed is now linked.
`Unmatched`	No company bank account has those numbers.
`Ambiguous`	More than one company bank account could be it, so none was chosen.
`AlreadyLinked`	The company bank account it matches is already fed by another connection.
`UnsupportedType`	The bank account is not a checking or savings account.
`MissingAuthNumbers`	The bank did not supply routing and account numbers that could be validated.

Nothing is linked if nothing matches

If not a single account can be matched, the call fails with 422 and no connection is stored. The problem detail carries an accountMatches array with the same shape as the success response, so you can show the property manager which accounts were rejected and why.