Presets

Set AI presets

Configures AI presets for matching, estimate, takeoff, or trade-report generation. Presets can be:

Global: Applied to all jobs of the selected workflow type (no storeReference or customerReference)
Store-level: Applied to jobs of the selected workflow type for a specific store/region (storeReference only)
Customer-level: Applied to jobs of the selected workflow type for a specific customer (customerReference, optionally with storeReference)

Hierarchy: Customer-specific → Store-specific → Global

Note: Setting presets for an existing scope will replace the previous presets entirely.

post/v1/presets

Request

Base URL: https://api.handoff.ai
URL: https://api.handoff.ai/v1/presets
Auth: HTTP bearer

Request body

forType'MATCHING' | 'ESTIMATE' | 'TAKEOFF' | 'TRADE_REPORT'

Preset workflow type. Defaults to MATCHING.

presetsstring[] required

List of preset instructions for the selected workflow type. An empty array clears all presets for the type and scope while preserving version history.

storeReferencestring

Store, location, or region identifier. If provided, presets apply to the selected workflow type for this store/region.

customerReferencestring

Customer identifier. If provided, presets apply to the selected workflow type for this customer. Takes priority over store-level presets.

changeDescriptionstring

Human-readable description of what changed in this version. Required when called from the internal admin UI; optional for external API consumers (backward-compatible).

targetClientIdstring uuid

Example request

{
  "forType": "MATCHING",
  "presets": [
    "Include 10% waste factor for all lumber",
    "Prefer in-stock items over special orders",
    "Use premium grade materials for structural components"
  ],
  "storeReference": "STORE-NYC-001",
  "customerReference": "CUST-12345",
  "changeDescription": "Added premium-materials preset for high-end residential customers"
}

Response

Presets successfully configured

presetIdstring uuid nullable required

Unique identifier for this preset configuration. Null if no presets exist yet.

storeReferencestring nullable required

Store reference if store-specific, null otherwise

customerReferencestring nullable required

Customer reference if customer-specific, null otherwise

forType'MATCHING' | 'ESTIMATE' | 'TAKEOFF' | 'TRADE_REPORT' required

Preset workflow type

presetsstring[] required

List of preset instructions

versioninteger required

Monotonic version number for this preset row. Starts at 1 and increments on every write.

changeDescriptionstring nullable required

Description of the change that produced the current version, or null for pre-versioning rows.

createdAtstring date-time required

ISO 8601 timestamp of preset creation

updatedAtstring date-time required

ISO 8601 timestamp of last update

warningsstring[]

Non-fatal validation warnings for the saved presets (e.g. a TAKEOFF_PRODUCT: tag naming an unknown product — such presets never apply to any job until fixed)

Example response

{
  "presetId": "e3f4a5b6-c7d8-4e9f-0a1b-2c3d4e5f6a7b",
  "storeReference": "STORE-NYC-001",
  "forType": "MATCHING",
  "presets": [
    "Include 10% waste factor for all lumber",
    "Prefer in-stock items over special orders",
    "Use premium grade materials for structural components"
  ],
  "version": 3,
  "changeDescription": "Added premium-materials preset for high-end residential customers",
  "createdAt": "2025-12-05T16:30:00Z",
  "updatedAt": "2025-12-05T16:30:00Z",
  "warnings": [
    "Preset 2 has an unrecognized TAKEOFF_PRODUCT tag (\"WINDOW_DOORS\") and will never apply to any job"
  ]
}

Changes

No recorded changes to this operation across all 1 revision of this API.