---
title: "Explicitly release inactive cash mappings and approve their replacements"
method: POST
path: "/accountant/companies/{customerId}/integrations/quickbooks/account-mapping-transfers"
tags: ["Accountants"]
---

# Explicitly release inactive cash mappings and approve their replacements

`POST /accountant/companies/{customerId}/integrations/quickbooks/account-mapping-transfers`

## Request

- Base URL: `https://api.medianfi.com/api/v1`
- URL: `https://api.medianfi.com/api/v1/accountant/companies/{customerId}/integrations/quickbooks/account-mapping-transfers`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-API-Key`

Dry run is the default and changes nothing. Apply requires the same source run, complete expected current mapping IDs, reason, exact transfers, expiry and digest returned by the dry run. In one transaction the API records immutable releases and replacement mappings with actor and API-key audit. Old QuickBooks accounts must be inactive Bank/Card accounts with no current source activity since the cutoff; replacements must be active accounts of the same type/currency on the same GL and cash source. Concurrent source/mapping or pending import/writeback work blocks apply. No bank/GL status, provenance, journal, provider or historical receipt is changed. Released old accounts with new activity hold imports instead of falling through to Ask My Accountant. Requires fresh accountant assignment; the reviewed service principal may call this high-impact route.

## Request body

- object
  - `dryRun` boolean
  - `expectedSourceRunId` string, uuid, required
  - `expectedMappingIds` string[], required
  - `reason` string, required
  - `expiresAt` string, date-time: Required on apply; copy the dry-run expiry (at most ten minutes).
  - `planDigest` string: Required on apply; copy the dry-run digest.
  - `transfers` object[], required
    - `oldMappingId` string, uuid, required
    - `newQboAccountId` string, required
    - `glAccountId` string, uuid, required
    - `cashSource` 'quickbooks' | 'median', required

## Response `200`

Prepared transfer plan or atomically applied mappings

- object
  - `success` true, required
  - `data` object, required
    - `dryRun` boolean, required
    - `sourceRunId` string, uuid, required
    - `expectedMappingIds` string[], required
    - `expiresAt` string, date-time, required
    - `planDigest` string, required
    - `transfers` object[], required
      - `oldMappingId` string, uuid, required
      - `oldQboAccountId` string, required
      - `newQboAccountId` string, required
      - `sourceObjectId` string, uuid, required
      - `glAccountId` string, uuid, required
      - `cashSource` 'quickbooks' | 'median', required
    - `mappings` QuickBooksAccountMapping[], required
      - `id` string, uuid, required
      - `companyId` string, uuid, required
      - `entityId` string, uuid, required
      - `connectionId` string, uuid, required
      - `realmId` string, required
      - `qboAccountId` string, required
      - `sourceObjectId` string, uuid, required
      - `glAccountId` string, uuid, required
      - `cashSource` 'quickbooks' | 'median', required
      - `approvedByUserId` string, uuid, required
      - `supersedesId` string, uuid, nullable, required
      - `createdAt` string, date-time, required

## Other responses

- `401`: Authentication required
- `403`: Insufficient permissions or not a company member
- `409`: Source, mappings, pending work or dry-run digest changed; prepare again
- `422`: Invalid economic replacement, source activity, scope, currency or reconciliation authority
- `503`: Selected account-reference projection is not verified (QUICKBOOKS_REFERENCE_PROJECTION_NOT_READY); no transfer is applied and no recursive fallback runs

---

[API](https://skmtc.dev/medianfi/apis/median-api.md) · [All operations](https://skmtc.dev/medianfi/apis/median-api/llms.txt) · [OpenAPI document](https://skmtc.dev/medianfi/apis/median-api/revisions/20090ea32b0d?raw)