Organization API

Create a project-contained Work Order

Creates a Work Order inside a required Project using an active Work Type. The Work Order Property is derived from the Project and submitted mismatches fail validation. Requires linking an existing unlinked WORK_ORDER Project Item or creating a limited inline Project Item in the same transaction. Scheduling fields are not writable. Requires Idempotency-Key and work_orders:write. notes is rejected: Work Order Notes was retired on 2026-10-27; send job instructions in description.

/api/v1/work-orders

Create a project-contained Work Order. Use an organization API key with work_orders:write. Check the response envelope and meta.requestId before triggering dependent workflow steps.

Required scopes

work_orders:writeIdempotency-Key required

Parameters

No path or query parameters.

Request body

objectrequired

Field	Type	Description
projectIdrequired	string	Optional unless marked required.
workTypeIdrequired	string	Optional unless marked required.
titlerequired	string	Optional unless marked required.
description	string \| null	Optional unless marked required.
priority	LOW \| MEDIUM \| HIGH \| URGENT	Optional unless marked required.
status	NOT_READY_TO_SCHEDULE \| READY_TO_SCHEDULE \| BLOCKED \| SCHEDULED \| IN_PROGRESS	Optional unless marked required.
estimatedHours	string \| number \| null	Optional unless marked required.
propertyId	string \| null	Optional unless marked required.
projectItemId	string \| null	Optional unless marked required.
projectItem	object	Optional unless marked required.
projectItem.stageId	string \| null	Optional unless marked required.
projectItem.name	string	Optional unless marked required.
projectItem.description	string \| null	Optional unless marked required.
projectItem.sortOrder	integer	Optional unless marked required.
projectItem.isRequired	boolean	Optional unless marked required.
projectItem.isCustomerVisible	boolean	Optional unless marked required.
projectItem.customerFacingName	string \| null	Optional unless marked required.
customFields	object	Field Values keyed by savedIdentity from GET /api/v1/schema.
externalReferences[]	array<object>	Optional unless marked required.
externalReferences[].externalSystemrequired	string	Optional unless marked required.
externalReferences[].externalObjectrequired	string	Optional unless marked required.
externalReferences[].externalIdrequired	string	Optional unless marked required.
externalReferences[].metadata	object	Optional unless marked required.
workOrderNumber	string	Optional unless marked required.

createworkorderRequest

{
  "projectId": "project_123",
  "workTypeId": "work_type_123",
  "title": "Install PV array",
  "description": "Roof work and inverter installation.",
  "priority": "MEDIUM",
  "projectItem": {
    "name": "Install PV array",
    "isRequired": true
  }
}

Responses

201

Created Work Order envelope

#/components/schemas/OrgApiResourceEnvelope

400

Validation, Project Item, stage, or idempotency error