--- title: imports.historyPreview | Doing Work API description: Dry run of a history import (kind jobs, quotes, invoices, pricebook, equipment, maintenance_plans, payments or flat_rate). Writes no shop data. url: https://doingwork.work/docs/reference/imports-historypreview/ --- # imports.historyPreview Dry run of a history import (kind jobs, quotes, invoices, pricebook, equipment, maintenance_plans, payments or flat_rate). Writes no shop data. Returns a suggested mapping, what each record would do (create, update, skip, skip_blank, skip_closed or error) with how its customer matched, and a preview_hash. Show it to the owner; imports.historyRun needs the same hash. include_won true (quotes only) imports won and declined quotes as history instead of skip_closed. History prices later drafts and is never sent or billed. Quote rows with a size column include sizes (400 sq ft) so the owner can confirm. A column header that is a unit supplies that unit. The description is used only when no size column is mapped. The Jobber preset is beta. Columns it cannot map are skipped, the summary says what would be skipped and why, and that skip is logged (column names and a short reason only). | | | |---|---| | Who | Agents can call this | | REST | `POST /v1/imports/history/preview` | | MCP tool | `imports_historyPreview` | | Writes | no | | Area | [Imports, custom fields, tags and search](https://doingwork.work/docs/reference/#imports-custom-fields-tags-and-search) | ## When to use it Dry run of a history import (kind jobs, quotes, invoices, pricebook, equipment, maintenance_plans, payments or flat_rate). Writes no shop data. ## What to tell the owner Tell them what you found in plain words. Don't read back raw fields. ## Input | Field | Type | Required | |---|---|---| | `shop_id` | string (uuid) | yes | | `plans_as` | string (one of reminders, billed) | no | | `include_won` | boolean | no | | `kind` | string (one of jobs, quotes, invoices, pricebook, equipment, maintenance_plans, payments, flat_rate) | yes | | `csv` | string | yes | | `source` | string | no | | `on_match` | string (one of skip, update) | no | | `mapping` | array | no | | `mapping[].column` | string | yes | | `mapping[].field` | string | yes | | `equipment_kind` | string | no | | `preset` | string (one of jobber, housecall_pro) | no | ## Example ```http POST https://doingwork.work/v1/imports/history/preview content-type: application/json Idempotency-Key: 3f1c... { "shop_id": "00000000-0000-4000-8000-000000000000", "kind": "jobs", "csv": "..." } ``` ## Output | Field | Type | Always there | |---|---|---| | `kind` | string | yes | | `source` | string | yes | | `on_match` | string | yes | | `include_won` | boolean | yes | | `equipment_kind` | ['string', 'null'] | yes | | `headers` | array | yes | | `mapping` | array | yes | | `preview_hash` | string | yes | | `records` | integer | yes | | `create` | integer | yes | | `update` | integer | yes | | `skip` | integer | yes | | `skip_closed` | integer | yes | | `failed` | integer | yes | | `row_errors` | array | yes | | `items` | array | yes | | `note` | ['string', 'null'] | no | | `summary` | string | no | | `skipped_columns` | array | no | ```json { "kind": "...", "source": "...", "on_match": "...", "include_won": true, "equipment_kind": "...", "headers": [ "..." ], "mapping": [ {} ], "preview_hash": "...", "records": 1, "create": 1, "update": 1, "skip": 1, "skip_closed": 1, "failed": 1, "row_errors": [ {} ], "items": [ {} ] } ``` ## Errors | Code | Status | What to do | |---|---|---| | `invalid_input`, `invalid_token`, `rate_limited` | | Can happen on any call. See [errors](https://doingwork.work/docs/errors/). |