> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xenia.team/llms.txt
> Use this file to discover all available pages before exploring further.

# Work Orders

> Create and manage facility requests and work orders with cost tracking

## 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).

<CodeGroup>
  ```bash cURL theme={null}
  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"]
    }'
  ```
</CodeGroup>

**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:**

```json theme={null}
{
  "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"
  }
}
```

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

***

## List Work Orders

Filter and list work orders.

<CodeGroup>
  ```bash cURL theme={null}
  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"]
      }
    }'
  ```
</CodeGroup>

**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:**

```json theme={null}
{
  "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.

<CodeGroup>
  ```bash cURL theme={null}
  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"]
    }'
  ```
</CodeGroup>

***

## Update Work Order Status

Progress the work order through its lifecycle.

<CodeGroup>
  ```bash cURL theme={null}
  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"
    }'
  ```
</CodeGroup>

**Work Order Status Flow:**

```mermaid theme={null}
graph LR
    A[Open] --> B[In Progress]
    B --> C[On Hold]
    C --> B
    B --> D[Completed]
    A --> E[Missed]
```

| 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

<Info>
  Cost tracking requires the `WORK_ORDER_COST` feature to be enabled for your workspace.
</Info>

### Add/Update Costs

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

<CodeGroup>
  ```bash cURL theme={null}
  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"]
    }'
  ```
</CodeGroup>

**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:**

```json theme={null}
{
  "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.

<CodeGroup>
  ```bash cURL theme={null}
  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"
        }
      ]
    }'
  ```
</CodeGroup>

### Delete a Cost

<CodeGroup>
  ```bash cURL theme={null}
  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}"
  ```
</CodeGroup>

***

## Service Types (Categories)

Service types categorize work orders for routing and reporting.

### List Service Types

<CodeGroup>
  ```bash cURL theme={null}
  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"
      }
    }'
  ```
</CodeGroup>

**Response:**

```json theme={null}
{
  "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

```mermaid theme={null}
sequenceDiagram
    participant Requester as Requester
    participant API as Xenia API
    participant Manager as Manager
    participant Tech as Technician

    Requester->>API: 1. POST /tasks/work-orders
    Note right of Requester: Create work order
    API-->>Requester: Work order created

    Manager->>API: 2. GET /tasks/list
    Note right of Manager: Review open requests

    Manager->>API: 3. PATCH /tasks/{id}/assign
    Note right of Manager: Assign technician

    Tech->>API: 4. PATCH /tasks/{id}/status
    Note right of Tech: Set "In Progress"

    Tech->>API: 5. POST /tasks/{id}/costs
    Note right of Tech: Log labor & parts

    Tech->>API: 6. PATCH /tasks/{id}/status
    Note right of Tech: Set "Completed"
```

### Create Work Order from Inspection

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

```bash theme={null}
#!/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

```bash theme={null}
#!/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.

<CodeGroup>
  ```bash cURL theme={null}
  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"
    }'
  ```
</CodeGroup>

***

## Delete Work Order

<CodeGroup>
  ```bash cURL theme={null}
  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}"
  ```
</CodeGroup>

***

## Best Practices

<AccordionGroup>
  <Accordion title="Use service types for routing">
    Categorize work orders with service types. This enables automatic routing to appropriate teams and better reporting by category.
  </Accordion>

  <Accordion title="Attach photos for context">
    Encourage requesters to attach photos when creating work orders. Visual context helps technicians prepare and diagnose issues faster.
  </Accordion>

  <Accordion title="Track all costs">
    Log labor, parts, and other expenses. This data is valuable for budgeting, asset lifecycle decisions, and identifying recurring issues.
  </Accordion>

  <Accordion title="Link to assets">
    Associate work orders with specific assets when applicable. This builds maintenance history for each piece of equipment.
  </Accordion>

  <Accordion title="Use priority appropriately">
    Reserve "High" priority for genuinely urgent issues. Overuse of high priority reduces its effectiveness and overwhelms technicians.
  </Accordion>

  <Accordion title="Set realistic due dates">
    Consider parts availability, technician workload, and complexity when setting due dates. Unrealistic dates lead to "Missed" status inflation.
  </Accordion>
</AccordionGroup>

***

## 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`                   |

***

## Related Guides

* [Task Management](/guides/workflows/task-management) - General task operations
* [Corrective Actions](/guides/workflows/corrective-actions) - Tasks from flagged items
* [Asset Management](/guides/workflows/asset-management) - Asset maintenance tracking
* [Submission Workflow](/guides/workflows/submission-workflow) - Inspections that generate work orders