Skip to content
HeyX API

Create Work Order

Required scope: work_order:create

POST /public-api/publicapi.v1.WorkOrder/CreateWorkOrder

customerId is always required. Without a template, provide a nonblank title and locationDataFieldId identifying a populated location field on that customer. Use Prepare Work Order to discover populated locations visible through the actor’s current Customer View. A field definition alone does not prove the customer has a usable location value.

Public creation independently checks the resolved field against the actor’s current Customer View, before querying whether it has a populated value. This applies to both an explicit locationDataFieldId and an inherited template preference. Hidden fields are rejected, even if their IDs are known. Preparation is discovery, not a lasting authorization grant; visibility is checked again at creation.

Title is limited to 200 characters, description to 20,000, and supplied manual tasks to 500 with bodies of 1 through 20,000 characters each.

The actor needs orders write access and customer write access. Template-backed creation additionally requires content-template read access. Being able to discover templates through settings read access alone does not authorize their instantiation.

Generated Reference
POST /public-api/publicapi.v1.WorkOrder/CreateWorkOrder

Creates a customer work order, optionally inheriting a template. Explicit title, description and location override defaults; tasks are appended. This operation is not idempotent.

Request CreateWorkOrderRequest
Response CreateWorkOrderResponse

CreateWorkOrderRequest

Field Type Description
customer_id string
location_data_field_id string ID from PrepareWorkOrder. May be omitted when the template's preferred field is populated on this customer. An explicit value overrides it.
title string Required without a template; omission inherits the template title.
description string
tasks repeated CreateWorkOrderTaskInput
work_order_template_id optional string

CreateWorkOrderResponse

Field Type
work_order WorkOrder

Related Types

CreateWorkOrderTaskInput

Field Type
body string

WorkOrder

Field Type
id string
customer_id string
title string
description string
status string
created_at int64
updated_at int64
customer_reference_number string
customer_title string
total_tasks int32
completed_tasks int32
work_order_template_id optional string 
{
  "customerId": "<customer-id>",
  "locationDataFieldId": "<location-data-field-id>",
  "title": "Install battery",
  "description": "Customer confirmed access",
  "tasks": [{ "body": "Mount enclosure" }]
}

Use a template

Section titled “Use a template”

Discover an active work-order template and inspect its preferred location and task counts before creating:

{
  "customerId": "<customer-id>",
  "workOrderTemplateId": "<work-order-template-id>"
}

Omitted title and empty description inherit template defaults. An explicit title, description, or location overrides its default; supplied manual tasks append to inherited tasks. locationDataFieldId may be omitted only when the template’s preferred field is visible, usable, and populated on this customer. If the template reports requiresLocationOverride, select an explicit populated location. Even when that flag is false, use preparation to check this customer’s available locations; the template flag describes a field definition, not its value.

Arbitrary workflow, advanced-task, configuration JSON, and order-relinking inputs are not exposed. Template creation is a separate operation. The response contains workOrder; use Get Work Order to inspect its tasks.

This operation is not idempotent. Do not blindly retry after a timeout.

HeyX API