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

# Work Orders API

> API endpoints for managing work orders

## Overview

The Work Orders API allows you to create, read, update, and manage work orders programmatically. This is useful for integrating Fentu FSM with other systems or building custom applications.

***

## Endpoints

### List Work Orders

Retrieve a list of work orders.

```
GET /api/v1/work-orders
```

**Query Parameters:**

| Parameter       | Type    | Description                              |
| --------------- | ------- | ---------------------------------------- |
| `page`          | integer | Page number (default: 1)                 |
| `per_page`      | integer | Results per page (default: 25, max: 100) |
| `status`        | string  | Filter by status                         |
| `customer_id`   | string  | Filter by customer                       |
| `technician_id` | string  | Filter by assigned technician            |
| `from_date`     | date    | Start date filter (YYYY-MM-DD)           |
| `to_date`       | date    | End date filter (YYYY-MM-DD)             |

**Example Request:**

```bash theme={null}
curl -X GET "https://api.fentu.io/v1/work-orders?status=open&per_page=10" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

**Example Response:**

```json theme={null}
{
  "data": [
    {
      "id": "wo-12345",
      "work_order_number": "WO-2024-001",
      "status": "open",
      "customer": {
        "id": "cust-001",
        "name": "Acme Corp"
      },
      "scheduled_date": "2024-01-27T09:00:00Z",
      "priority": "high",
      "created_at": "2024-01-20T14:30:00Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "total_pages": 5,
    "total_count": 47
  }
}
```

***

### Get Work Order

Retrieve a single work order by ID.

```
GET /api/v1/work-orders/{id}
```

**Example Request:**

```bash theme={null}
curl -X GET "https://api.fentu.io/v1/work-orders/wo-12345" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

**Example Response:**

```json theme={null}
{
  "data": {
    "id": "wo-12345",
    "work_order_number": "WO-2024-001",
    "status": "open",
    "priority": "high",
    "description": "Annual Machine maintenance",
    "customer": {
      "id": "cust-001",
      "name": "Acme Corp",
      "address": "123 Main St, City, ST 12345"
    },
    "contact": {
      "id": "contact-001",
      "name": "John Smith",
      "phone": "+1-555-123-4567"
    },
    "scheduled_date": "2024-01-27T09:00:00Z",
    "estimated_duration": 120,
    "technician": {
      "id": "tech-001",
      "name": "Jane Doe"
    },
    "tasks": [
      {
        "id": "task-001",
        "name": "Inspect filters",
        "status": "pending"
      }
    ],
    "created_at": "2024-01-20T14:30:00Z",
    "updated_at": "2024-01-25T10:15:00Z"
  }
}
```

***

### Create Work Order

Create a new work order.

```
POST /api/v1/work-orders
```

**Request Body:**

```json theme={null}
{
  "customer_id": "cust-001",
  "contact_id": "contact-001",
  "work_order_type": "service",
  "priority": "medium",
  "description": "Repair air conditioning unit",
  "scheduled_date": "2024-02-01T10:00:00Z",
  "estimated_duration": 90,
  "technician_id": "tech-001",
  "notes": "Customer requests morning appointment"
}
```

**Example Request:**

```bash theme={null}
curl -X POST "https://api.fentu.io/v1/work-orders" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "cust-001",
    "work_order_type": "service",
    "priority": "medium",
    "description": "Repair air conditioning unit"
  }'
```

**Example Response:**

```json theme={null}
{
  "data": {
    "id": "wo-12346",
    "work_order_number": "WO-2024-002",
    "status": "open",
    "created_at": "2024-01-27T15:00:00Z"
  }
}
```

***

### Update Work Order

Update an existing work order.

```
PUT /api/v1/work-orders/{id}
```

**Request Body:**

```json theme={null}
{
  "status": "in_progress",
  "technician_id": "tech-002",
  "scheduled_date": "2024-02-02T14:00:00Z"
}
```

**Example Request:**

```bash theme={null}
curl -X PUT "https://api.fentu.io/v1/work-orders/wo-12345" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": "in_progress"}'
```

***

### Delete Work Order

Delete a work order (moves to trash).

```
DELETE /api/v1/work-orders/{id}
```

**Example Request:**

```bash theme={null}
curl -X DELETE "https://api.fentu.io/v1/work-orders/wo-12345" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

***

## Work Order Statuses

| Status        | Description                    |
| ------------- | ------------------------------ |
| `draft`       | Not yet submitted              |
| `open`        | Submitted, awaiting assignment |
| `assigned`    | Assigned to technician         |
| `in_progress` | Work has started               |
| `on_hold`     | Temporarily paused             |
| `completed`   | Work finished                  |
| `cancelled`   | Work order cancelled           |

***

## Error Responses

| Code  | Description                          |
| ----- | ------------------------------------ |
| `400` | Bad request - invalid parameters     |
| `401` | Unauthorized - invalid token         |
| `403` | Forbidden - insufficient permissions |
| `404` | Not found - work order doesn't exist |
| `422` | Validation error                     |

**Error Response Format:**

```json theme={null}
{
  "error": {
    "code": "validation_error",
    "message": "Validation failed",
    "details": [
      {
        "field": "customer_id",
        "message": "Customer not found"
      }
    ]
  }
}
```

***

## Related Documentation

<CardGroup cols={2}>
  <Card title="Tasks API" icon="tasks" href="/api-reference/endpoints/tasks">
    Task endpoints
  </Card>

  <Card title="Customers API" icon="users" href="/api-reference/endpoints/customers">
    Customer endpoints
  </Card>

  <Card title="Authentication" icon="key" href="/api-reference/authentication">
    API authentication
  </Card>

  <Card title="Work Orders" icon="clipboard-list" href="/work-orders/work-orders">
    Work order user guide
  </Card>
</CardGroup>