Task Management

Overview

Tasks are the core work units in Xenia. This guide covers creating tasks, updating their status, managing assignments, and tracking task activity. Key Concepts:

One-off Tasks: Single tasks with a specific due date
Recurring Tasks: Tasks that repeat on a schedule (see Task Scheduling)
Work Orders: Facility requests from requesters (see Work Orders)

Create a Task

Create a new one-off task with assignees and optional checklist attachment.

curl -X POST "https://api.xenia.team/api/v1/ops/workspaces/{workspaceId}/tasks" \
  -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": "Weekly Safety Inspection",
    "description": "Complete the standard safety inspection checklist",
    "startDate": "2024-12-20T09:00:00Z",
    "dueDate": "2024-12-20T17:00:00Z",
    "priority": "High",
    "assignees": ["user-uuid-1", "user-uuid-2"],
    "locationIds": ["location-uuid"],
    "AssetId": "asset-uuid",
    "ChecklistId": "checklist-template-uuid",
    "isChecklistRequired": true,
    "notification": {
      "email": true,
      "push": true
    }
  }'

Request Body:

Field	Type	Required	Description
`title`	string	Yes	Task title
`description`	string	No	Task description
`additionalDescription`	string	No	Extended description/notes
`startDate`	datetime	Yes	When the task becomes active
`dueDate`	datetime	No	When the task is due
`startTime`	string	No	Specific start time (HH:MM format)
`dueTime`	string	No	Specific due time (HH:MM format)
`priority`	string	No	`None`, `Low`, `Medium`, `High`
`assignees`	string[]	No	Array of user IDs to assign
`locationIds`	string[]	No	Array of location IDs
`AssetId`	string	No	Related asset ID
`ChecklistId`	string	No	Template to attach for completion
`isChecklistRequired`	boolean	No	Require checklist completion before task completion
`isTimeBound`	boolean	No	Whether task has strict time boundaries
`notification`	object	No	Notification preferences
`attachment`	string[]	No	Array of attachment file paths
`ServiceTypeId`	string	No	Task category/service type ID

Response:

{
  "status": "success",
  "code": 200,
  "data": {
    "id": "task-uuid",
    "title": "Weekly Safety Inspection",
    "description": "Complete the standard safety inspection checklist",
    "taskStatus": "Open",
    "priority": "High",
    "startDate": "2024-12-20T09:00:00Z",
    "dueDate": "2024-12-20T17:00:00Z",
    "taskNumber": "T-2024-001234",
    "Assignees": [
      {
        "id": "user-uuid-1",
        "fullName": "John Smith"
      }
    ],
    "Location": {
      "id": "location-uuid",
      "name": "Building A"
    },
    "createdAt": "2024-12-19T10:00:00Z"
  }
}

Create Multiple Tasks (One Per Assignee)

Set isMultiTasks: true to create separate tasks for each assignee.

curl -X POST "https://api.xenia.team/api/v1/ops/workspaces/{workspaceId}/tasks" \
  -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": "Complete Training Module",
    "startDate": "2024-12-20T09:00:00Z",
    "dueDate": "2024-12-27T17:00:00Z",
    "assignees": ["user-uuid-1", "user-uuid-2", "user-uuid-3"],
    "isMultiTasks": true
  }'

This creates 3 separate tasks, one for each assignee.

Get Tasks

List Tasks with Filters

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": "dueDate",
      "direction": "ASC"
    },
    "searchText": "safety",
    "filters": {
      "taskStatus": ["Open", "In Progress"],
      "priority": ["High", "Medium"],
      "assigneeIds": ["user-uuid"],
      "locationIds": ["location-uuid"],
      "dateFrom": "2024-12-01",
      "dateTo": "2024-12-31"
    }
  }'

Request Body:

Field	Type	Required	Description
`page`	number	Yes	Page number (1-indexed)
`pageSize`	number	Yes	Items per page (max 100)
`sort`	object	Yes	Sort configuration
`sort.field`	string	Yes	Field to sort by
`sort.direction`	string	Yes	`ASC` or `DESC`
`searchText`	string	No	Search in title/description
`filters`	object	No	Filter criteria

Filter Options:

Filter	Type	Description
`taskStatus`	string[]	Filter by status(es)
`priority`	string[]	Filter by priority level(s)
`assigneeIds`	string[]	Filter by assignee(s)
`locationIds`	string[]	Filter by location(s)
`assetIds`	string[]	Filter by asset(s)
`dateFrom`	string	Start date (YYYY-MM-DD)
`dateTo`	string	End date (YYYY-MM-DD)
`isOverdue`	boolean	Only overdue tasks

Response:

{
  "status": "success",
  "code": 200,
  "data": {
    "tasks": [
      {
        "id": "task-uuid-1",
        "title": "Weekly Safety Inspection",
        "taskStatus": "Open",
        "priority": "High",
        "dueDate": "2024-12-20T17:00:00Z",
        "taskNumber": "T-2024-001234",
        "Assignees": [...],
        "Location": {...}
      }
    ],
    "meta": {
      "total": 45,
      "page": 1,
      "pageSize": 20,
      "totalPages": 3
    }
  }
}

Get Task Details

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

Response:

{
  "status": "success",
  "code": 200,
  "data": {
    "id": "task-uuid",
    "title": "Weekly Safety Inspection",
    "description": "Complete the standard safety inspection checklist",
    "taskStatus": "In Progress",
    "priority": "High",
    "startDate": "2024-12-20T09:00:00Z",
    "dueDate": "2024-12-20T17:00:00Z",
    "taskNumber": "T-2024-001234",
    "Assignees": [
      {
        "id": "user-uuid",
        "fullName": "John Smith",
        "email": "[email protected]"
      }
    ],
    "Location": {
      "id": "location-uuid",
      "name": "Building A"
    },
    "Asset": {
      "id": "asset-uuid",
      "name": "Fire Extinguisher #42"
    },
    "Checklist": {
      "id": "checklist-uuid",
      "title": "Safety Checklist"
    },
    "ChecklistLog": {
      "id": "submission-uuid",
      "status": "in_progress"
    },
    "Creator": {
      "id": "creator-uuid",
      "fullName": "Jane Doe"
    },
    "attachments": [
      {
        "url": "https://storage.example.com/attachment.pdf",
        "name": "instructions.pdf"
      }
    ],
    "canEdit": true,
    "canChangeStatus": true,
    "canDelete": true,
    "createdAt": "2024-12-19T10:00:00Z",
    "updatedAt": "2024-12-20T11:30:00Z"
  }
}

Get Task Count Summary

Get counts of tasks by status.

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

Response:

{
  "status": "success",
  "code": 200,
  "data": {
    "Open": 25,
    "In Progress": 12,
    "On Hold": 3,
    "Completed": 156,
    "Missed": 8,
    "total": 204
  }
}

Update Task Status

Set Task Status

curl -X PATCH "https://api.xenia.team/api/v1/ops/workspaces/{workspaceId}/tasks/{taskId}/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"
  }'

Task Status Values:

Status	Description
`Open`	Task is created but not started
`In Progress`	Task is being worked on
`On Hold`	Task is paused
`Completed`	Task is finished
`Missed`	Task was not completed by due date

Response:

{
  "status": "success",
  "code": 200,
  "data": {
    "id": "task-uuid",
    "taskStatus": "In Progress",
    "updatedAt": "2024-12-20T11:30:00Z"
  }
}

If a task has isChecklistRequired: true, the attached checklist must be submitted before the task can be marked as Completed.

Reopen a Completed Task

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

Archive a Task

Soft-delete a task (can be recovered).

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

Edit Task

Update task details.

curl -X POST "https://api.xenia.team/api/v1/ops/workspaces/{workspaceId}/tasks/{taskId}/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 Task Title",
    "description": "Updated description",
    "dueDate": "2024-12-25T17:00:00Z",
    "priority": "Medium"
  }'

Editable Fields:

title, description, additionalDescription
startDate, dueDate, startTime, dueTime
priority
locationIds, AssetId
ChecklistId, isChecklistRequired
notification
attachment
ServiceTypeId

Manage Assignees

Add Assignee to Task

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

Remove Assignee from Task

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

Replace All Assignees

curl -X PATCH "https://api.xenia.team/api/v1/ops/workspaces/{workspaceId}/tasks/{taskId}/assignees" \
  -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": ["user-uuid-1", "user-uuid-2"]
  }'

Claim Task

User claims an unassigned or pool task.

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

Return Task

Return a claimed task back to the pool.

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

Bulk Operations

Bulk Update Tasks

Update multiple tasks at once.

curl -X PATCH "https://api.xenia.team/api/v1/ops/workspaces/{workspaceId}/tasks/bulk-update" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "x-client-secret: YOUR_CLIENT_SECRET" \
  -H "workspace-id: {workspaceId}" \
  -H "Content-Type: application/json" \
  -d '{
    "taskIds": ["task-uuid-1", "task-uuid-2", "task-uuid-3"],
    "updates": {
      "priority": "High",
      "assignees": ["user-uuid"]
    }
  }'

Task Activity

Get Task Activity Log

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

Response:

{
  "status": "success",
  "code": 200,
  "data": [
    {
      "id": "activity-uuid-1",
      "action": "status_changed",
      "details": {
        "from": "Open",
        "to": "In Progress"
      },
      "User": {
        "id": "user-uuid",
        "fullName": "John Smith"
      },
      "createdAt": "2024-12-20T11:30:00Z"
    },
    {
      "id": "activity-uuid-2",
      "action": "assignee_added",
      "details": {
        "assignee": "Jane Doe"
      },
      "User": {
        "id": "user-uuid",
        "fullName": "John Smith"
      },
      "createdAt": "2024-12-19T10:00:00Z"
    }
  ]
}

Delete Task

Permanently delete a task.

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

This permanently deletes the task and cannot be undone. Use archive for soft deletion.

Export Tasks

Export to CSV

curl -X POST "https://api.xenia.team/api/v1/ops/workspaces/{workspaceId}/tasks/csv" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "x-client-secret: YOUR_CLIENT_SECRET" \
  -H "workspace-id: {workspaceId}" \
  -H "Content-Type: application/json" \
  -d '{
    "filters": {
      "dateFrom": "2024-12-01",
      "dateTo": "2024-12-31"
    }
  }'

Response: CSV file content

Common Workflows

Task with Required Checklist

Assign and Track Task

#!/bin/bash
# Create task, assign, and monitor

WORKSPACE_ID="your-workspace-uuid"

# 1. Create task
TASK=$(curl -s -X POST "https://api.xenia.team/api/v1/ops/workspaces/${WORKSPACE_ID}/tasks" \
  -H "x-client-key: YOUR_KEY" \
  -H "x-client-secret: YOUR_SECRET" \
  -H "workspace-id: ${WORKSPACE_ID}" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Equipment Maintenance",
    "startDate": "2024-12-20T09:00:00Z",
    "dueDate": "2024-12-20T17:00:00Z",
    "priority": "High"
  }')

TASK_ID=$(echo $TASK | jq -r '.data.id')

# 2. Add assignee
curl -X POST "https://api.xenia.team/api/v1/ops/workspaces/${WORKSPACE_ID}/tasks/${TASK_ID}/assignees/user-uuid" \
  -H "x-client-key: YOUR_KEY" \
  -H "x-client-secret: YOUR_SECRET" \
  -H "workspace-id: ${WORKSPACE_ID}"

# 3. Check task status
curl -X GET "https://api.xenia.team/api/v1/ops/workspaces/${WORKSPACE_ID}/tasks/${TASK_ID}/details" \
  -H "x-client-key: YOUR_KEY" \
  -H "x-client-secret: YOUR_SECRET" \
  -H "workspace-id: ${WORKSPACE_ID}"

Best Practices

Use appropriate task status transitions

Follow the natural flow: Open → In Progress → Completed. Avoid skipping statuses for accurate reporting.

Attach checklists for standardized work

When tasks require specific steps or inspections, attach a checklist template. Set isChecklistRequired: true to enforce completion.

Use locations and assets for context

Always associate tasks with locations and assets when applicable. This improves filtering, reporting, and mobile worker routing.

Set realistic due dates

Consider timezone differences when setting due dates. Use startTime and dueTime for time-sensitive tasks.

Use bulk operations for efficiency

When updating multiple tasks (e.g., reassigning), use the bulk update endpoint instead of individual calls.

Task Scheduling - Recurring tasks and schedules
Work Orders - Facility request management
Corrective Actions - Tasks from flagged items
Project Management - Organize related tasks
Template Management - Create checklists for tasks

Getting Started

Workflows

Integrations

Overview

Create a Task

Create Multiple Tasks (One Per Assignee)

Get Tasks

List Tasks with Filters

Get Task Details

Get Task Count Summary

Update Task Status

Set Task Status

Reopen a Completed Task

Archive a Task

Edit Task

Manage Assignees

Add Assignee to Task

Remove Assignee from Task

Replace All Assignees

Claim Task

Return Task

Bulk Operations

Bulk Update Tasks

Task Activity

Get Task Activity Log

Delete Task

Export Tasks

Export to CSV

Common Workflows

Task with Required Checklist

Assign and Track Task

Best Practices

Getting Started

Workflows

Integrations

​Overview

​Create a Task

​Create Multiple Tasks (One Per Assignee)

​Get Tasks

​List Tasks with Filters

​Get Task Details

​Get Task Count Summary

​Update Task Status

​Set Task Status

​Reopen a Completed Task

​Archive a Task

​Edit Task

​Manage Assignees

​Add Assignee to Task

​Remove Assignee from Task

​Replace All Assignees

​Claim Task

​Return Task

​Bulk Operations

​Bulk Update Tasks

​Task Activity

​Get Task Activity Log

​Delete Task

​Export Tasks

​Export to CSV

​Common Workflows

​Task with Required Checklist

​Assign and Track Task

​Best Practices

​Related Guides

Overview

Create a Task

Create Multiple Tasks (One Per Assignee)

Get Tasks

List Tasks with Filters

Get Task Details

Get Task Count Summary

Update Task Status

Set Task Status

Reopen a Completed Task

Archive a Task

Edit Task

Manage Assignees

Add Assignee to Task

Remove Assignee from Task

Replace All Assignees

Claim Task

Return Task

Bulk Operations

Bulk Update Tasks

Task Activity

Get Task Activity Log

Delete Task

Export Tasks

Export to CSV

Common Workflows

Task with Required Checklist

Assign and Track Task

Best Practices

Related Guides