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