Work Orders

Overview

Work orders are facility maintenance requests that flow through a request-to-completion workflow. They support cost tracking, approval workflows, and can be submitted by requesters (users with limited permissions). Key Differences from Tasks:

Work orders can be created by “Requester” role users
Include cost tracking capabilities
Follow request → assignment → completion flow
Often triggered by issues discovered during inspections

Create a Work Order

Create a new work order (facility request).

curl -X POST "https://api.xenia.team/api/v1/ops/workspaces/{workspaceId}/tasks/work-orders" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "x-client-secret: YOUR_CLIENT_SECRET" \
  -H "workspace-id: {workspaceId}" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "HVAC Unit Not Cooling - Room 302",
    "description": "Guest reported AC not working. Room temperature at 78°F despite thermostat set to 68°F.",
    "startDate": "2024-12-20T09:00:00Z",
    "dueDate": "2024-12-20T17:00:00Z",
    "priority": "High",
    "locationIds": ["location-uuid"],
    "AssetId": "hvac-unit-asset-uuid",
    "ServiceTypeId": "hvac-category-uuid",
    "attachment": ["https://storage.example.com/photos/hvac-issue.jpg"]
  }'

Request Body:

Field	Type	Required	Description
`title`	string	Yes	Work order title/summary
`description`	string	No	Detailed description of the issue
`startDate`	datetime	Yes	When work should begin
`dueDate`	datetime	No	When work should be completed
`priority`	string	No	`None`, `Low`, `Medium`, `High`
`locationIds`	string[]	No	Affected location(s)
`AssetId`	string	No	Related asset/equipment
`ServiceTypeId`	string	No	Category (HVAC, Plumbing, Electrical, etc.)
`assignees`	string[]	No	Assigned technicians (can be assigned later)
`attachment`	string[]	No	Photos or documents

Response:

{
  "status": "success",
  "code": 200,
  "data": {
    "id": "work-order-uuid",
    "title": "HVAC Unit Not Cooling - Room 302",
    "taskStatus": "Open",
    "priority": "High",
    "isRequested": true,
    "taskNumber": "WO-2024-000456",
    "Location": {
      "id": "location-uuid",
      "name": "Room 302"
    },
    "Asset": {
      "id": "hvac-unit-asset-uuid",
      "name": "HVAC Unit #42"
    },
    "ServiceType": {
      "id": "hvac-category-uuid",
      "name": "HVAC"
    },
    "createdAt": "2024-12-19T14:30:00Z"
  }
}

Work orders are created with isRequested: true internally, which distinguishes them from regular tasks in reporting and permissions.

List Work Orders

Filter and list work orders.

curl -X POST "https://api.xenia.team/api/v1/ops/workspaces/{workspaceId}/tasks/list" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "x-client-secret: YOUR_CLIENT_SECRET" \
  -H "workspace-id: {workspaceId}" \
  -H "Content-Type: application/json" \
  -d '{
    "page": 1,
    "pageSize": 20,
    "sort": {
      "field": "createdAt",
      "direction": "DESC"
    },
    "filters": {
      "isRequested": true,
      "taskStatus": ["Open", "In Progress"],
      "priority": ["High", "Medium"]
    }
  }'

Work Order Specific Filters:

Filter	Type	Description
`isRequested`	boolean	`true` to filter only work orders
`ServiceTypeId`	string	Filter by category
`hasAsset`	boolean	Filter work orders with/without assets

Response:

{
  "status": "success",
  "code": 200,
  "data": {
    "tasks": [
      {
        "id": "work-order-uuid",
        "title": "HVAC Unit Not Cooling - Room 302",
        "taskStatus": "In Progress",
        "priority": "High",
        "isRequested": true,
        "taskNumber": "WO-2024-000456",
        "Assignees": [
          {
            "id": "tech-uuid",
            "fullName": "Mike Johnson"
          }
        ],
        "Location": {...},
        "Asset": {...},
        "costs": {
          "total": 150.00,
          "itemCount": 2
        }
      }
    ],
    "meta": {
      "total": 28,
      "page": 1,
      "pageSize": 20
    }
  }
}

Assign Work Order

Assign a technician to a work order.

curl -X PATCH "https://api.xenia.team/api/v1/ops/workspaces/{workspaceId}/tasks/{workOrderId}/assign" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "x-client-secret: YOUR_CLIENT_SECRET" \
  -H "workspace-id: {workspaceId}" \
  -H "Content-Type: application/json" \
  -d '{
    "assignees": ["technician-uuid"]
  }'

Update Work Order Status

Progress the work order through its lifecycle.

curl -X PATCH "https://api.xenia.team/api/v1/ops/workspaces/{workspaceId}/tasks/{workOrderId}/status" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "x-client-secret: YOUR_CLIENT_SECRET" \
  -H "workspace-id: {workspaceId}" \
  -H "Content-Type: application/json" \
  -d '{
    "taskStatus": "In Progress"
  }'

Work Order Status Flow:

Status	Description
`Open`	Request submitted, awaiting assignment or start
`In Progress`	Technician actively working
`On Hold`	Waiting for parts, approval, or other dependency
`Completed`	Work finished
`Missed`	Not completed by due date

Cost Tracking

Cost tracking requires the WORK_ORDER_COST feature to be enabled for your workspace.

Add/Update Costs

Add labor, parts, or other costs to a work order.

curl -X POST "https://api.xenia.team/api/v1/ops/workspaces/{workspaceId}/tasks/{workOrderId}/costs" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "x-client-secret: YOUR_CLIENT_SECRET" \
  -H "workspace-id: {workspaceId}" \
  -H "Content-Type: application/json" \
  -d '{
    "costs": [
      {
        "amount": 75.00,
        "description": "Labor - 1.5 hours @ $50/hr",
        "CostCreatedBy": "technician-uuid"
      },
      {
        "amount": 125.50,
        "description": "Replacement capacitor - Part #AC-CAP-440",
        "CostCreatedBy": "technician-uuid"
      }
    ],
    "attachments": ["https://storage.example.com/receipts/part-receipt.pdf"]
  }'

Request Body:

Field	Type	Required	Description
`costs`	array	Yes	Array of cost items
`costs[].id`	string	No	Include to update existing cost
`costs[].amount`	number	Yes	Cost amount
`costs[].description`	string	No	Description of cost
`costs[].CostCreatedBy`	string	Yes	User ID who logged the cost
`attachments`	string[]	No	Receipt/invoice attachments

Response:

{
  "status": "success",
  "code": 200,
  "data": {
    "costs": [
      {
        "id": "cost-uuid-1",
        "amount": 75.00,
        "description": "Labor - 1.5 hours @ $50/hr",
        "CostCreatedBy": "technician-uuid",
        "createdAt": "2024-12-20T11:30:00Z"
      },
      {
        "id": "cost-uuid-2",
        "amount": 125.50,
        "description": "Replacement capacitor - Part #AC-CAP-440",
        "CostCreatedBy": "technician-uuid",
        "createdAt": "2024-12-20T11:30:00Z"
      }
    ],
    "totalCost": 200.50
  }
}

Update Existing Cost

Include the cost id to update an existing entry.

curl -X POST "https://api.xenia.team/api/v1/ops/workspaces/{workspaceId}/tasks/{workOrderId}/costs" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "x-client-secret: YOUR_CLIENT_SECRET" \
  -H "workspace-id: {workspaceId}" \
  -H "Content-Type: application/json" \
  -d '{
    "costs": [
      {
        "id": "cost-uuid-1",
        "amount": 100.00,
        "description": "Labor - 2 hours @ $50/hr (updated)",
        "CostCreatedBy": "technician-uuid"
      }
    ]
  }'

Delete a Cost

curl -X DELETE "https://api.xenia.team/api/v1/ops/workspaces/{workspaceId}/tasks/{workOrderId}/costs/{costId}" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "x-client-secret: YOUR_CLIENT_SECRET" \
  -H "workspace-id: {workspaceId}"

Service Types (Categories)

Service types categorize work orders for routing and reporting.

List Service Types

curl -X POST "https://api.xenia.team/api/v1/ops/workspaces/{workspaceId}/categories" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "x-client-secret: YOUR_CLIENT_SECRET" \
  -H "workspace-id: {workspaceId}" \
  -H "Content-Type: application/json" \
  -d '{
    "page": 1,
    "pageSize": 50,
    "sort": {
      "field": "name",
      "direction": "ASC"
    }
  }'

Response:

{
  "status": "success",
  "code": 200,
  "data": {
    "categories": [
      {
        "id": "category-uuid-1",
        "name": "HVAC",
        "description": "Heating, ventilation, and air conditioning"
      },
      {
        "id": "category-uuid-2",
        "name": "Plumbing",
        "description": "Water and drainage systems"
      },
      {
        "id": "category-uuid-3",
        "name": "Electrical",
        "description": "Electrical systems and lighting"
      }
    ]
  }
}

Common Workflows

Work Order Lifecycle

Create Work Order from Inspection

When a flagged item is found during an inspection, create a work order.

#!/bin/bash
# Create work order from flagged inspection item

WORKSPACE_ID="your-workspace-uuid"

# Get flagged items from recent submissions
FLAGGED=$(curl -s -X POST "https://api.xenia.team/api/v1/ops/workspaces/${WORKSPACE_ID}/submissions/flagged-items" \
  -H "x-client-key: YOUR_KEY" \
  -H "x-client-secret: YOUR_SECRET" \
  -H "workspace-id: ${WORKSPACE_ID}" \
  -H "Content-Type: application/json" \
  -d '{
    "dateFrom": "2024-12-19",
    "dateTo": "2024-12-20"
  }')

# For each flagged item, create a work order
echo $FLAGGED | jq -c '.data[]' | while read item; do
  TITLE=$(echo $item | jq -r '.flaggedItem.title')
  LOCATION_ID=$(echo $item | jq -r '.location.id')
  NOTE=$(echo $item | jq -r '.flaggedItem.flagNote')

  curl -X POST "https://api.xenia.team/api/v1/ops/workspaces/${WORKSPACE_ID}/tasks/work-orders" \
    -H "x-client-key: YOUR_KEY" \
    -H "x-client-secret: YOUR_SECRET" \
    -H "workspace-id: ${WORKSPACE_ID}" \
    -H "Content-Type: application/json" \
    -d "{
      \"title\": \"Fix: ${TITLE}\",
      \"description\": \"${NOTE}\",
      \"startDate\": \"$(date -u +%Y-%m-%dT%H:%M:%SZ)\",
      \"priority\": \"High\",
      \"locationIds\": [\"${LOCATION_ID}\"]
    }"
done

Track Work Order Costs

#!/bin/bash
# Generate cost report for work orders

WORKSPACE_ID="your-workspace-uuid"

# Get completed work orders with costs
curl -s -X POST "https://api.xenia.team/api/v1/ops/workspaces/${WORKSPACE_ID}/tasks/list" \
  -H "x-client-key: YOUR_KEY" \
  -H "x-client-secret: YOUR_SECRET" \
  -H "workspace-id: ${WORKSPACE_ID}" \
  -H "Content-Type: application/json" \
  -d '{
    "page": 1,
    "pageSize": 100,
    "filters": {
      "isRequested": true,
      "taskStatus": ["Completed"],
      "dateFrom": "2024-12-01",
      "dateTo": "2024-12-31"
    }
  }' | jq '.data.tasks[] | {
    taskNumber: .taskNumber,
    title: .title,
    totalCost: .costs.total,
    completedAt: .completedAt
  }'

Edit Work Order

Update work order details.

curl -X POST "https://api.xenia.team/api/v1/ops/workspaces/{workspaceId}/tasks/{workOrderId}/edit" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "x-client-secret: YOUR_CLIENT_SECRET" \
  -H "workspace-id: {workspaceId}" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Updated: HVAC Unit Repair - Room 302",
    "description": "Updated diagnosis: Capacitor failure confirmed",
    "priority": "High",
    "dueDate": "2024-12-21T12:00:00Z"
  }'

Delete Work Order

curl -X DELETE "https://api.xenia.team/api/v1/ops/workspaces/{workspaceId}/tasks/{workOrderId}" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "x-client-secret: YOUR_CLIENT_SECRET" \
  -H "workspace-id: {workspaceId}"

Best Practices

Use service types for routing

Categorize work orders with service types. This enables automatic routing to appropriate teams and better reporting by category.

Attach photos for context

Encourage requesters to attach photos when creating work orders. Visual context helps technicians prepare and diagnose issues faster.

Track all costs

Log labor, parts, and other expenses. This data is valuable for budgeting, asset lifecycle decisions, and identifying recurring issues.

Link to assets

Associate work orders with specific assets when applicable. This builds maintenance history for each piece of equipment.

Use priority appropriately

Reserve “High” priority for genuinely urgent issues. Overuse of high priority reduces its effectiveness and overwhelms technicians.

Set realistic due dates

Consider parts availability, technician workload, and complexity when setting due dates. Unrealistic dates lead to “Missed” status inflation.

Permissions

Action	Required Permission
Create work order	`CAN_MANAGE_WORK_ORDERS` or Requester role
View work orders	`CAN_VIEW_WORK_ORDERS`
Assign work order	`CAN_MANAGE_WORK_ORDERS`
Update status	`CAN_CHANGE_WORK_ORDER_STATUS`
Add costs	`CAN_MANAGE_WORK_ORDERS`
Delete work order	`CAN_MANAGE_WORK_ORDERS`

Task Management - General task operations
Corrective Actions - Tasks from flagged items
Asset Management - Asset maintenance tracking
Submission Workflow - Inspections that generate work orders

Getting Started

Workflows

Integrations

Overview

Create a Work Order

List Work Orders

Assign Work Order

Update Work Order Status

Cost Tracking

Add/Update Costs

Update Existing Cost

Delete a Cost

Service Types (Categories)

List Service Types

Common Workflows

Work Order Lifecycle

Create Work Order from Inspection

Track Work Order Costs

Edit Work Order

Delete Work Order

Best Practices

Permissions

Getting Started

Workflows

Integrations

​Overview

​Create a Work Order

​List Work Orders

​Assign Work Order

​Update Work Order Status

​Cost Tracking

​Add/Update Costs

​Update Existing Cost

​Delete a Cost

​Service Types (Categories)

​List Service Types

​Common Workflows

​Work Order Lifecycle

​Create Work Order from Inspection

​Track Work Order Costs

​Edit Work Order

​Delete Work Order

​Best Practices

​Permissions

​Related Guides

Overview

Create a Work Order

List Work Orders

Assign Work Order

Update Work Order Status

Cost Tracking

Add/Update Costs

Update Existing Cost

Delete a Cost

Service Types (Categories)

List Service Types

Common Workflows

Work Order Lifecycle

Create Work Order from Inspection

Track Work Order Costs

Edit Work Order

Delete Work Order

Best Practices

Permissions

Related Guides