Skip to content
XOS Developers

Update a work order

Work module

PATCH/work-orders/{id}workOrders.update

A work order issued against a record, open to bids. Updates the fields sent; omitted fields are unchanged. Requires `If-Match` with the current `ETag`: a stale tag returns 412 and a missing tag returns 428.

  • Requires the capability work.work_order.write.
  • OAuth scopes: work.
  • Send If-Match with the ETag you read. A stale tag returns 412; a missing tag returns 428.
  • Error statuses: 400, 401, 404, 412, 422, 428, 429. Errors are RFC 9457 problem details.

Path and query parameters

workOrders.update: Path and query parameters
FieldTypeRequiredDescription
idstring (uuid)YesIdentifier of the work order.

Request body: WorkOrderUpdate

workOrders.update: WorkOrderUpdate
FieldTypeRequiredDescription
record_idstring (uuid) | nullNoIdentifier of the record the work order fulfills.
titlestringNoWork order title.Constraints: length 1 to 300
uridUridAtAnyGrainNoURID at discipline grain (`DDDD.DD`) or category grain (`DDDD.DD.DD`), as GL dimension 2 allows.Constraints: pattern ^[0-9]000(\.[0-9]{2}){1,2}$
due_atstring (date-time) | nullNoWhen the work is due.
budget_minorinteger (int64) | nullNoBudget for the work. Integer minor units of the resource currency; null means unpriced, never zero.
currencystringNoISO 4217 currency code of every money field.Constraints: pattern ^[A-Z]{3}$
location_textstring | nullNoWhere the work happens, in words, when no zone says it.Constraints: length 1 to 300
scope_of_workstring | nullNoThe scope bidders price, in sentence case.Constraints: length 1 to 20000
scheduled_starts_atstring (date-time) | nullNoPlanned start.
estimated_hoursnumber | nullNoEstimated labor hours; null when unestimated.
{
  "record_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
  "title": "Fabricate Bar Fascia",
  "due_at": "2026-10-08T14:30:00Z",
  "budget_minor": 850000,
  "currency": "USD",
  "location_text": "Main stage, stage left wing.",
  "scope_of_work": "Supply and hang 24 moving lights.",
  "scheduled_starts_at": "2026-10-08T14:30:00Z",
  "estimated_hours": 16
}

Response 200: WorkOrder

workOrders.update: WorkOrder
FieldTypeRequiredDescription
idstring (uuid)YesIdentifier of the work order.
org_idstring (uuid)YesIdentifier of the owning organization, derived from the parent row and never accepted from the caller.
created_atstring (date-time)YesWhen the row was created.
created_bystring (uuid) | nullYesIdentifier of the person who created the row; null when a seed, platform or system process created it.
updated_atstring (date-time)YesWhen the row was last updated.
updated_bystring (uuid) | nullYesIdentifier of the person who last updated the row; null when a seed, platform or system process updated it.
project_idstring (uuid)YesIdentifier of the project.
record_idstring (uuid) | nullYesIdentifier of the record the work order fulfills.
titlestringYesWork order title.Constraints: length 1 to 300
uridUridAtAnyGrainYesURID at discipline grain (`DDDD.DD`) or category grain (`DDDD.DD.DD`), as GL dimension 2 allows.Constraints: pattern ^[0-9]000(\.[0-9]{2}){1,2}$
work_order_statestringYesWork order state. A Title Case value from the lifecycle's database enum.Constraints: pattern ^[A-Z0-9][A-Za-z0-9&'/.()-]*( [A-Za-z0-9&'/.()-]+)*$
due_atstring (date-time) | nullYesWhen the work is due.
budget_minorinteger (int64) | nullYesBudget for the work. Integer minor units of the resource currency; null means unpriced, never zero.
currencystringYesISO 4217 currency code of every money field.Constraints: pattern ^[A-Z]{3}$
work_order_numberintegerYesSequence number within the project; the display key is {project_key}-WO-{number}.Constraints: range 1 to any
location_textstring | nullYesWhere the work happens, in words, when no zone says it.Constraints: length 1 to 300
scope_of_workstring | nullYesThe scope bidders price, in sentence case.Constraints: length 1 to 20000
scheduled_starts_atstring (date-time) | nullYesPlanned start.
estimated_hoursnumber | nullYesEstimated labor hours; null when unestimated.
{
  "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
  "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
  "created_at": "2026-10-08T14:30:00Z",
  "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
  "updated_at": "2026-10-08T14:30:00Z",
  "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
  "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
  "record_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
  "title": "Fabricate Bar Fascia",
  "urid": "4000.01",
  "work_order_state": "Proposed",
  "due_at": "2026-10-08T14:30:00Z",
  "budget_minor": 850000,
  "currency": "USD",
  "work_order_number": 12,
  "location_text": "Main stage, stage left wing.",
  "scope_of_work": "Supply and hang 24 moving lights.",
  "scheduled_starts_at": "2026-10-08T14:30:00Z",
  "estimated_hours": 16
}

Code samples

curl -X PATCH "$XOS_BASE_URL/work-orders/0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f" \
  -H "Authorization: Bearer $XOS_API_KEY" \
  -H 'If-Match: W/"etag-from-your-last-read"' \
  -H "Content-Type: application/json" \
  -d '{"record_id":"0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f","title":"Fabricate Bar Fascia","due_at":"2026-10-08T14:30:00Z","budget_minor":850000,"currency":"USD","location_text":"Main stage, stage left wing.","scope_of_work":"Supply and hang 24 moving lights.","scheduled_starts_at":"2026-10-08T14:30:00Z","estimated_hours":16}'
const { data, etag } = await xos.workOrders.update("0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", {
    "record_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
    "title": "Fabricate Bar Fascia",
    "due_at": "2026-10-08T14:30:00Z",
    "budget_minor": 850000,
    "currency": "USD",
    "location_text": "Main stage, stage left wing.",
    "scope_of_work": "Supply and hang 24 moving lights.",
    "scheduled_starts_at": "2026-10-08T14:30:00Z",
    "estimated_hours": 16
  }, { ifMatch: etag });
response = xos.work_orders.update("0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", {"record_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "title": "Fabricate Bar Fascia", "due_at": "2026-10-08T14:30:00Z", "budget_minor": 850000, "currency": "USD", "location_text": "Main stage, stage left wing.", "scope_of_work": "Supply and hang 24 moving lights.", "scheduled_starts_at": "2026-10-08T14:30:00Z", "estimated_hours": 16}, if_match=etag)
xos work-orders update 0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f --data '{"record_id":"0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f","title":"Fabricate Bar Fascia","due_at":"2026-10-08T14:30:00Z","budget_minor":850000,"currency":"USD","location_text":"Main stage, stage left wing.","scope_of_work":"Supply and hang 24 moving lights.","scheduled_starts_at":"2026-10-08T14:30:00Z","estimated_hours":16}' --if-match auto