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

# Template Management

> Create, configure, and publish inspection templates (checklists)

## Overview

Templates (also called checklists) are the blueprints for inspections, audits, and forms in Xenia. A template defines:

* **Sections**: Logical groupings of questions
* **Items**: Individual questions with response types and scoring
* **Notifications**: Automated alerts based on answers
* **Approval Workflows**: Review processes for completed submissions

***

## Key Concepts

### Template Structure

```
Template (Checklist)
├── Section 1
│   ├── Item 1 (Question)
│   ├── Item 2 (Question)
│   └── Item 3 (Question)
├── Section 2
│   ├── Item 4 (Question)
│   └── Item 5 (Question)
└── Notifications
    └── Alert on flagged items
```

### Template States

| State       | Description                                     |
| ----------- | ----------------------------------------------- |
| `draft`     | Work in progress, not available for submissions |
| `published` | Active and available for use                    |
| `archived`  | Deactivated, not available for new submissions  |

***

## Template CRUD Operations

### List Templates

Retrieve all templates in your workspace.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.xenia.team/api/v1/ops/workspaces/{workspaceId}/checklists" \
    -H "x-client-key: YOUR_CLIENT_KEY" \
    -H "x-client-secret: YOUR_CLIENT_SECRET" \
    -H "workspace-id: {workspaceId}"
  ```
</CodeGroup>

**Response:**

```json theme={null}
{
  "status": "success",
  "code": 200,
  "data": [
    {
      "id": "template-uuid-1",
      "name": "Daily Safety Inspection",
      "description": "Daily safety checklist for all sites",
      "isPublished": true,
      "isArchived": false,
      "category": "Safety",
      "type": "Inspection",
      "FolderId": "folder-uuid",
      "itemCount": 25,
      "sectionCount": 5,
      "createdAt": "2024-01-15T10:00:00Z",
      "updatedAt": "2024-06-20T14:30:00Z"
    }
  ]
}
```

### Get Template by ID

Retrieve a specific template with full details.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.xenia.team/api/v1/ops/workspaces/{workspaceId}/checklists/{checklistId}" \
    -H "x-client-key: YOUR_CLIENT_KEY" \
    -H "x-client-secret: YOUR_CLIENT_SECRET" \
    -H "workspace-id: {workspaceId}"
  ```
</CodeGroup>

**Response:**

```json theme={null}
{
  "status": "success",
  "code": 200,
  "data": {
    "id": "template-uuid",
    "name": "Daily Safety Inspection",
    "description": "Daily safety checklist for all sites",
    "isPublished": true,
    "isArchived": false,
    "category": "Safety",
    "type": "Inspection",
    "industry": "Manufacturing",
    "icon": "safety",
    "scoringEnabled": true,
    "passingScore": 80,
    "sections": [
      {
        "id": "section-uuid-1",
        "title": "PPE Check",
        "description": "Personal Protective Equipment verification",
        "order": 1,
        "items": [
          {
            "id": "item-uuid-1",
            "title": "Hard hat available and in good condition?",
            "type": "yesNo",
            "required": true,
            "order": 1,
            "scoring": {
              "enabled": true,
              "yesScore": 10,
              "noScore": 0,
              "naScore": 0
            }
          }
        ]
      }
    ],
    "notifications": [],
    "WorkspaceId": "workspace-uuid",
    "createdAt": "2024-01-15T10:00:00Z"
  }
}
```

### Create or Update Template

Create a new template or update an existing one (upsert).

<CodeGroup>
  ```bash cURL theme={null}
  curl -X PUT "https://api.xenia.team/api/v1/ops/workspaces/{workspaceId}/checklists/{checklistId}" \
    -H "x-client-key: YOUR_CLIENT_KEY" \
    -H "x-client-secret: YOUR_CLIENT_SECRET" \
    -H "workspace-id: {workspaceId}" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Daily Safety Inspection",
      "description": "Comprehensive daily safety checklist",
      "category": "Safety",
      "type": "Inspection",
      "industry": "Manufacturing",
      "scoringEnabled": true,
      "passingScore": 80,
      "sections": [
        {
          "title": "PPE Check",
          "description": "Personal Protective Equipment verification",
          "order": 1,
          "items": [
            {
              "title": "Hard hat available and in good condition?",
              "type": "yesNo",
              "required": true,
              "order": 1,
              "scoring": {
                "enabled": true,
                "yesScore": 10,
                "noScore": 0
              }
            },
            {
              "title": "Safety glasses worn?",
              "type": "yesNo",
              "required": true,
              "order": 2
            }
          ]
        },
        {
          "title": "Equipment Inspection",
          "order": 2,
          "items": [
            {
              "title": "Equipment condition",
              "type": "multipleChoice",
              "required": true,
              "options": [
                {"label": "Excellent", "score": 10},
                {"label": "Good", "score": 8},
                {"label": "Fair", "score": 5},
                {"label": "Poor", "score": 0, "flagged": true}
              ],
              "order": 1
            }
          ]
        }
      ]
    }'
  ```
</CodeGroup>

**Request Body:**

| Field            | Type    | Required | Description                      |
| ---------------- | ------- | -------- | -------------------------------- |
| `name`           | string  | Yes      | Template name                    |
| `description`    | string  | No       | Template description             |
| `category`       | string  | No       | Category (Safety, Quality, etc.) |
| `type`           | string  | No       | Type (Inspection, Audit, Form)   |
| `industry`       | string  | No       | Industry classification          |
| `scoringEnabled` | boolean | No       | Enable scoring for this template |
| `passingScore`   | number  | No       | Minimum passing score (0-100)    |
| `sections`       | array   | No       | Array of sections with items     |
| `FolderId`       | UUID    | No       | Folder to organize template      |

<Note>
  **Permission Required:** `CAN_MANAGE_CHECKLIST` or `CHECKLIST_SUPER_ADMIN`
</Note>

### Partial Update Template

Update specific fields without replacing the entire template.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X PATCH "https://api.xenia.team/api/v1/ops/workspaces/{workspaceId}/checklists/{checklistId}" \
    -H "x-client-key: YOUR_CLIENT_KEY" \
    -H "x-client-secret: YOUR_CLIENT_SECRET" \
    -H "workspace-id: {workspaceId}" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Updated Safety Inspection",
      "passingScore": 85
    }'
  ```
</CodeGroup>

### Delete Template

<CodeGroup>
  ```bash cURL theme={null}
  curl -X DELETE "https://api.xenia.team/api/v1/ops/workspaces/{workspaceId}/checklists/{checklistId}" \
    -H "x-client-key: YOUR_CLIENT_KEY" \
    -H "x-client-secret: YOUR_CLIENT_SECRET" \
    -H "workspace-id: {workspaceId}"
  ```
</CodeGroup>

<Warning>
  Deleting a template removes it permanently. Consider archiving instead if you want to preserve historical submissions.
</Warning>

***

## Template Items (Questions)

### Question Types

| Type             | Description                   | Example                                    |
| ---------------- | ----------------------------- | ------------------------------------------ |
| `yesNo`          | Yes/No toggle                 | "Is the area clean?"                       |
| `multipleChoice` | Single selection from options | "Rate condition: Excellent/Good/Fair/Poor" |
| `checkbox`       | Multiple selections           | "Select all hazards present"               |
| `text`           | Free text input               | "Describe any issues found"                |
| `number`         | Numeric input                 | "Temperature reading"                      |
| `date`           | Date picker                   | "Last inspection date"                     |
| `dateTime`       | Date and time                 | "Incident time"                            |
| `slider`         | Range slider                  | "Satisfaction (1-10)"                      |
| `signature`      | Signature capture             | "Inspector signature"                      |
| `photo`          | Image attachment              | "Photo of equipment"                       |
| `file`           | File attachment               | "Upload documentation"                     |

### Get Template Items

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.xenia.team/api/v1/ops/workspaces/{workspaceId}/checklists/{checklistId}/items" \
    -H "x-client-key: YOUR_CLIENT_KEY" \
    -H "x-client-secret: YOUR_CLIENT_SECRET" \
    -H "workspace-id: {workspaceId}"
  ```
</CodeGroup>

### Create or Update Item

<CodeGroup>
  ```bash cURL theme={null}
  curl -X PUT "https://api.xenia.team/api/v1/ops/workspaces/{workspaceId}/checklists/{checklistId}/items/{itemId}" \
    -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": "Fire extinguisher inspection",
      "description": "Check pressure gauge and inspection tag",
      "type": "yesNo",
      "required": true,
      "sectionId": "section-uuid",
      "order": 5,
      "scoring": {
        "enabled": true,
        "yesScore": 10,
        "noScore": 0,
        "naScore": 5
      },
      "flagOnAnswer": "no",
      "flagMessage": "Fire extinguisher needs attention"
    }'
  ```
</CodeGroup>

**Item Configuration:**

| Field              | Type    | Description                         |
| ------------------ | ------- | ----------------------------------- |
| `title`            | string  | Question text                       |
| `description`      | string  | Help text or instructions           |
| `type`             | string  | Question type (see table above)     |
| `required`         | boolean | Whether answer is required          |
| `sectionId`        | UUID    | Section this item belongs to        |
| `order`            | number  | Display order within section        |
| `scoring.enabled`  | boolean | Include in score calculation        |
| `scoring.yesScore` | number  | Points for "Yes" answer             |
| `scoring.noScore`  | number  | Points for "No" answer              |
| `scoring.naScore`  | number  | Points for "N/A" answer             |
| `options`          | array   | Options for multipleChoice/checkbox |
| `flagOnAnswer`     | string  | Answer value that triggers flag     |
| `flagMessage`      | string  | Message shown when flagged          |

### Delete Item

<CodeGroup>
  ```bash cURL theme={null}
  curl -X DELETE "https://api.xenia.team/api/v1/ops/workspaces/{workspaceId}/checklists/{checklistId}/items/{itemId}" \
    -H "x-client-key: YOUR_CLIENT_KEY" \
    -H "x-client-secret: YOUR_CLIENT_SECRET" \
    -H "workspace-id: {workspaceId}"
  ```
</CodeGroup>

***

## Publishing Templates

### Publish Template

Make a template available for submissions.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.xenia.team/api/v1/ops/workspaces/{workspaceId}/checklists/{checklistId}/publish" \
    -H "x-client-key: YOUR_CLIENT_KEY" \
    -H "x-client-secret: YOUR_CLIENT_SECRET" \
    -H "workspace-id: {workspaceId}"
  ```
</CodeGroup>

<Note>
  **Permission Required:** `CAN_PUBLISH_CHECKLIST` or `CHECKLIST_SUPER_ADMIN`

  **Feature Required:** `PUBLISH_CHECKLISTS` feature flag
</Note>

### Toggle Publish State

<CodeGroup>
  ```bash cURL theme={null}
  curl -X PUT "https://api.xenia.team/api/v1/ops/workspaces/{workspaceId}/checklists/{checklistId}/toggle-publish" \
    -H "x-client-key: YOUR_CLIENT_KEY" \
    -H "x-client-secret: YOUR_CLIENT_SECRET" \
    -H "workspace-id: {workspaceId}"
  ```
</CodeGroup>

### Unarchive Template

Restore an archived template.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X PUT "https://api.xenia.team/api/v1/ops/workspaces/{workspaceId}/checklists/{checklistId}/unarchive" \
    -H "x-client-key: YOUR_CLIENT_KEY" \
    -H "x-client-secret: YOUR_CLIENT_SECRET" \
    -H "workspace-id: {workspaceId}"
  ```
</CodeGroup>

***

## Template Folders

Organize templates into folders for better management.

### List Folders

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.xenia.team/api/v1/ops/workspaces/{workspaceId}/folders" \
    -H "x-client-key: YOUR_CLIENT_KEY" \
    -H "x-client-secret: YOUR_CLIENT_SECRET" \
    -H "workspace-id: {workspaceId}"
  ```
</CodeGroup>

### Create Folder

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.xenia.team/api/v1/ops/workspaces/{workspaceId}/folders" \
    -H "x-client-key: YOUR_CLIENT_KEY" \
    -H "x-client-secret: YOUR_CLIENT_SECRET" \
    -H "workspace-id: {workspaceId}" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Safety Inspections",
      "description": "All safety-related templates"
    }'
  ```
</CodeGroup>

### Move Templates to Folder

<CodeGroup>
  ```bash cURL theme={null}
  curl -X PUT "https://api.xenia.team/api/v1/ops/workspaces/{workspaceId}/checklists/update-folder" \
    -H "x-client-key: YOUR_CLIENT_KEY" \
    -H "x-client-secret: YOUR_CLIENT_SECRET" \
    -H "workspace-id: {workspaceId}" \
    -H "Content-Type: application/json" \
    -d '{
      "checklistIds": ["template-uuid-1", "template-uuid-2"],
      "folderId": "folder-uuid"
    }'
  ```
</CodeGroup>

### Remove Templates from Folder

<CodeGroup>
  ```bash cURL theme={null}
  curl -X PUT "https://api.xenia.team/api/v1/ops/workspaces/{workspaceId}/checklists/unset-folder" \
    -H "x-client-key: YOUR_CLIENT_KEY" \
    -H "x-client-secret: YOUR_CLIENT_SECRET" \
    -H "workspace-id: {workspaceId}" \
    -H "Content-Type: application/json" \
    -d '{
      "checklistIds": ["template-uuid-1"]
    }'
  ```
</CodeGroup>

***

## Template Notifications

Configure automated notifications based on submission answers.

### List Notifications

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.xenia.team/api/v1/ops/workspaces/{workspaceId}/checklists/{checklistId}/notifications" \
    -H "x-client-key: YOUR_CLIENT_KEY" \
    -H "x-client-secret: YOUR_CLIENT_SECRET" \
    -H "workspace-id: {workspaceId}"
  ```
</CodeGroup>

### Create Notification

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.xenia.team/api/v1/ops/workspaces/{workspaceId}/checklists/{checklistId}/notifications" \
    -H "x-client-key: YOUR_CLIENT_KEY" \
    -H "x-client-secret: YOUR_CLIENT_SECRET" \
    -H "workspace-id: {workspaceId}" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Safety Alert",
      "trigger": "flaggedItem",
      "channels": ["email", "push"],
      "recipients": {
        "userIds": ["user-uuid-1"],
        "roleIds": ["safety-manager-role-uuid"]
      },
      "message": "A safety issue was flagged during inspection"
    }'
  ```
</CodeGroup>

**Notification Configuration:**

| Field                | Type   | Description                                        |
| -------------------- | ------ | -------------------------------------------------- |
| `name`               | string | Notification name                                  |
| `trigger`            | string | When to send: `flaggedItem`, `submission`, `score` |
| `channels`           | array  | Delivery channels: `email`, `push`, `sms`          |
| `recipients.userIds` | array  | Specific user IDs to notify                        |
| `recipients.roleIds` | array  | Role IDs to notify all members                     |
| `message`            | string | Notification message                               |
| `scoreThreshold`     | number | For score triggers, threshold value                |

### Update Notification

<CodeGroup>
  ```bash cURL theme={null}
  curl -X PUT "https://api.xenia.team/api/v1/ops/workspaces/{workspaceId}/checklists/{checklistId}/notifications/{notificationId}" \
    -H "x-client-key: YOUR_CLIENT_KEY" \
    -H "x-client-secret: YOUR_CLIENT_SECRET" \
    -H "workspace-id: {workspaceId}" \
    -H "Content-Type: application/json" \
    -d '{
      "message": "Updated notification message"
    }'
  ```
</CodeGroup>

### Delete Notification

<CodeGroup>
  ```bash cURL theme={null}
  curl -X DELETE "https://api.xenia.team/api/v1/ops/workspaces/{workspaceId}/checklists/{checklistId}/notifications/{notificationId}" \
    -H "x-client-key: YOUR_CLIENT_KEY" \
    -H "x-client-secret: YOUR_CLIENT_SECRET" \
    -H "workspace-id: {workspaceId}"
  ```
</CodeGroup>

***

## Template Duplication

### Duplicate Template

Create a copy of an existing template.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.xenia.team/api/v1/ops/workspaces/{workspaceId}/checklists/{checklistId}/duplicate" \
    -H "x-client-key: YOUR_CLIENT_KEY" \
    -H "x-client-secret: YOUR_CLIENT_SECRET" \
    -H "workspace-id: {workspaceId}"
  ```
</CodeGroup>

**Response:**

```json theme={null}
{
  "status": "success",
  "code": 200,
  "data": {
    "id": "new-template-uuid",
    "name": "Daily Safety Inspection (Copy)",
    "isPublished": false
  }
}
```

***

## Reference Data

### Get Categories

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.xenia.team/api/v1/ops/workspaces/{workspaceId}/checklist-categories" \
    -H "x-client-key: YOUR_CLIENT_KEY" \
    -H "x-client-secret: YOUR_CLIENT_SECRET" \
    -H "workspace-id: {workspaceId}"
  ```
</CodeGroup>

### Get Types

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.xenia.team/api/v1/ops/workspaces/{workspaceId}/checklist-types" \
    -H "x-client-key: YOUR_CLIENT_KEY" \
    -H "x-client-secret: YOUR_CLIENT_SECRET" \
    -H "workspace-id: {workspaceId}"
  ```
</CodeGroup>

### Get Industries

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.xenia.team/api/v1/ops/workspaces/{workspaceId}/checklist-industries" \
    -H "x-client-key: YOUR_CLIENT_KEY" \
    -H "x-client-secret: YOUR_CLIENT_SECRET" \
    -H "workspace-id: {workspaceId}"
  ```
</CodeGroup>

***

## Common Workflows

### Creating a Complete Template

```mermaid theme={null}
sequenceDiagram
    participant API as Xenia API
    participant Client as Your System

    Client->>API: 1. PUT /checklists/{id}
    Note right of Client: Create template with sections & items
    API-->>Client: Template created (draft)

    Client->>API: 2. POST /checklists/{id}/notifications
    Note right of Client: Add notification rules
    API-->>Client: Notifications configured

    Client->>API: 3. POST /checklists/{id}/approval
    Note right of Client: Configure approval workflow
    API-->>Client: Approval workflow set

    Client->>API: 4. POST /checklists/{id}/publish
    Note right of Client: Make available for submissions
    API-->>Client: Template published
```

### Migrating Templates from External System

```bash theme={null}
# Step 1: Create template structure
TEMPLATE_ID="new-template-uuid"
curl -X PUT ".../checklists/${TEMPLATE_ID}" \
  -d '{
    "name": "Imported Checklist",
    "sections": [
      {
        "title": "Section 1",
        "items": [...]
      }
    ]
  }'

# Step 2: Add to folder
curl -X PUT ".../checklists/update-folder" \
  -d "{
    \"checklistIds\": [\"${TEMPLATE_ID}\"],
    \"folderId\": \"imported-folder-uuid\"
  }"

# Step 3: Publish when ready
curl -X POST ".../checklists/${TEMPLATE_ID}/publish"
```

***

## Best Practices

<AccordionGroup>
  <Accordion title="Design templates for reuse">
    Create modular sections that can be combined. Use clear naming conventions and descriptions.
  </Accordion>

  <Accordion title="Use scoring strategically">
    Enable scoring for compliance-critical templates. Set passing scores that align with your quality standards.
  </Accordion>

  <Accordion title="Configure appropriate notifications">
    Set up alerts for flagged items to ensure immediate attention to safety or quality issues.
  </Accordion>

  <Accordion title="Test before publishing">
    Create test submissions for new templates to verify question flow, scoring, and notifications work as expected.
  </Accordion>

  <Accordion title="Organize with folders">
    Group related templates into folders (by department, location, or category) for easier management.
  </Accordion>

  <Accordion title="Version control via duplication">
    Before major changes, duplicate the template. This preserves the original and allows rollback if needed.
  </Accordion>
</AccordionGroup>

***

## Related Guides

* [Submission Workflow](/guides/workflows/submission-workflow) - Complete inspections using templates
* [Submission Exports](/guides/workflows/submission-exports) - Export submission data
* [Submission Approvals](/guides/workflows/submission-approvals) - Configure approval workflows