---
title: "Prepare a draft QuickBooks write-back batch (#2642)"
method: POST
path: "/accountant/companies/{customerId}/integrations/quickbooks/writebacks"
tags: ["Accountants"]
---

# Prepare a draft QuickBooks write-back batch (#2642)

`POST /accountant/companies/{customerId}/integrations/quickbooks/writebacks`

## Request

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

Stores, for review, the exact QuickBooks request of every selected item with its SHA-256, a stable Intuit `requestid`, and the batch manifest hash that approve and post must present. Nothing is sent to QuickBooks. Named `journalEntryIds` are kept even when blocked (as `blocked` items with their reason); a `dateFrom`/`dateTo` range adds only eligible entries. `sparseUpdates` correct an object pulled from QuickBooks (Purchase or Deposit): `glAccountId` is reverse-mapped to its single QuickBooks account, `classId` is a QuickBooks Class Id, `memo` sets the private note. Amounts, dates and the bank/card account are never changed. 422 QUICKBOOKS_WRITEBACK_NOTHING_ELIGIBLE when no item is eligible; 409 when an entry is already held by another batch.

## Request body

- object
  - `journalEntryIds` string[]
  - `dateFrom` string, date
  - `dateTo` string, date
  - `sparseUpdates` object[]
    - `linkId` string, uuid, required
    - `expectedSourceObjectId` string, uuid
    - `glAccountId` string, uuid
    - `classId` string
    - `memo` string
    - `lineIds` string[]

## Response `201`

The draft batch with its items

- object
  - `success` true, required
  - `data` QuickBooksWritebackBatchDetail, required
    - `batch` QuickBooksWritebackBatch, required
      - `id` string, uuid, required
      - `companyId` string, uuid, required
      - `entityId` string, uuid, required
      - `connectionId` string, uuid, required
      - `realmId` string, required
      - `cutoffId` string, uuid, required
      - `dateFrom` string, date, nullable, required
      - `dateTo` string, date, nullable, required
      - `status` 'draft' | 'approved' | 'posting' | 'posted' | 'failed' | 'cancelled', required
      - `manifestSha256` string, required
      - `preparedByUserId` string, uuid, required
      - `preparedAt` string, date-time, required
      - `approvedByUserId` string, uuid, nullable, required
      - `approvedAt` string, date-time, nullable, required
      - `postedByUserId` string, uuid, nullable, required
      - `postingStartedAt` string, date-time, nullable, required
      - `postedAt` string, date-time, nullable, required
      - `cancelledByUserId` string, uuid, nullable, required
      - `cancelledAt` string, date-time, nullable, required
      - `errorCode` string, nullable, required
    - `items` QuickBooksWritebackItem[], required
      - `id` string, uuid, required
      - `batchId` string, uuid, required
      - `companyId` string, uuid
      - `kind` 'create_journal_entry' | 'sparse_update' | 'create_account' | 'create_transaction' | 'delete_transaction', required: create_transaction and delete_transaction are the automatic bank-feed push (#2642 phase 2)
      - `journalEntryId` string, uuid, nullable, required
      - `linkId` string, uuid, nullable, required
      - `glAccountId` string, uuid, nullable, required: The Median GL account a create_account (chart push) item creates, maps or skips; null for other kinds
      - `transactionId` string, uuid, nullable, required: The native bank-feed transaction a bank-feed push item (create_transaction, delete_transaction, or a sparse_update of a pushed object) concerns; null otherwise
      - `requestId` string, uuid, required: Intuit requestid idempotency key
      - `requestSha256` string, required
      - `payload` object, required: The exact QuickBooks request body (amounts as decimal strings; sent as JSON numbers)
      - `expected` object, required: What the read-back must show (or the block reasons of a blocked item)
      - `status` 'pending' | 'approved' | 'sending' | 'sent' | 'verified' | 'failed' | 'blocked' | 'cancelled', required
      - `blockCode` string, nullable, required
      - `qboObjectType` 'JournalEntry' | 'Purchase' | 'Deposit' | 'Account', required
      - `qboId` string, nullable, required
      - `qboSyncToken` string, nullable, required
      - `readbackSha256` string, nullable, required
      - `pushLinkId` string, uuid, nullable, required
      - `attempts` integer, required
      - `lastErrorCode` string, nullable, required
      - `preparedByUserId` string, uuid
      - `preparedAt` string, date-time
      - `approvedByUserId` string, uuid, nullable
      - `approvedAt` string, date-time, nullable
      - `sentAt` string, date-time, nullable
      - `verifiedAt` string, date-time, nullable

## Other responses

- `401`: Authentication required
- `403`: Insufficient permissions or not a company member
- `409`: An entry or object is already held by another write-back batch
- `422`: Validation error, unknown entry or link, nothing eligible, no cutoff, or QuickBooks not connected

---

[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)