---
title: "Map unmapped QuickBooks accounts automatically (#2642)"
method: POST
path: "/accountant/companies/{customerId}/integrations/quickbooks/account-mappings/auto"
tags: ["Accountants"]
---

# Map unmapped QuickBooks accounts automatically (#2642)

`POST /accountant/companies/{customerId}/integrations/quickbooks/account-mappings/auto`

## Request

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

Fills only QuickBooks accounts with no current mapping (an existing mapping always wins), from the latest completed QuickBooks read, in order: system role (A/R, A/P, retained earnings, opening balance equity), connected bank/card last four digits, exact account number or name. For an established QuickBooks file (a transaction dated before the posting cutoff), also creates a Median account mirroring each remaining QuickBooks account, renames role-matched system accounts to the QuickBooks name, and deactivates unused Median accounts that have no QuickBooks counterpart. A new file (or no cutoff) gets matches only. Idempotent; nothing posts. The same run happens after every completed QuickBooks read.

## Request body

- object

## Response `200`

What this run did

- object
  - `success` true, required
  - `data` QuickBooksAutoMapSummary, required
    - `mode` 'established' | 'new_file', required
    - `mapped` integer, required
    - `created` integer, required
    - `deactivated` integer, required
    - `renamed` integer, required
    - `exceptions` QuickBooksAutoMapException[], required
      - `qboAccountId` string, nullable, required: Null for a Median account with no QuickBooks counterpart
      - `glAccountId` string, uuid
      - `name` string, required
      - `reason` 'multiple_for_system_role' | 'ambiguous' | 'unknown_type' | 'no_match' | 'name_conflict' | 'no_free_code' | 'create_failed' | 'median_account_not_in_quickbooks' | 'quickbooks_account_inactive' | 'quickbooks_account_reactivated', required
      - `candidates` QuickBooksAutoMapGlAccountRef[]
        - `glAccountId` string, uuid, required
        - `code` string, required
        - `name` string, required
    - `medianSystemAccountsKept` QuickBooksAutoMapGlAccountRef[], required
      - `glAccountId` string, uuid, required
      - `code` string, required
      - `name` string, required

## Other responses

- `401`: Authentication required
- `403`: Insufficient permissions or not a company member
- `409`: A mapping changed concurrently; run again
- `422`: Validation error, QuickBooks not connected, or no completed QuickBooks read
- `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)