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

WhoAgents can call this
RESTPOST /v1/imports/history/preview
MCP toolimports_historyPreview
Writesno
AreaImports, 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

FieldTypeRequired
shop_idstring (uuid)yes
plans_asstring (one of reminders, billed)no
include_wonbooleanno
kindstring (one of jobs, quotes, invoices, pricebook, equipment, maintenance_plans, payments, flat_rate)yes
csvstringyes
sourcestringno
on_matchstring (one of skip, update)no
mappingarrayno
mapping[].columnstringyes
mapping[].fieldstringyes
equipment_kindstringno
presetstring (one of jobber, housecall_pro)no

Example

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

FieldTypeAlways there
kindstringyes
sourcestringyes
on_matchstringyes
include_wonbooleanyes
equipment_kind['string', 'null']yes
headersarrayyes
mappingarrayyes
preview_hashstringyes
recordsintegeryes
createintegeryes
updateintegeryes
skipintegeryes
skip_closedintegeryes
failedintegeryes
row_errorsarrayyes
itemsarrayyes
note['string', 'null']no
summarystringno
skipped_columnsarrayno
{
  "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

CodeStatusWhat to do
invalid_input, invalid_token, rate_limitedCan happen on any call. See errors.