Tasks

The Task entity (internally ApiTask / TaskItem) represents tasks within a project. Via the OData API, you can create, update, delete tasks and use batch processing, contributors, stopwatch features, and calendar synchronization.

OData Endpoint Base

All endpoints use the base path /odata/Task. For the dynamic list view including custom fields, /odata/DynamicTaskItem is available.

---

Data Model

Property	Type	Description
TaskItemId	Guid (UUID)	Unique identifier of the task (primary key).
Name	string?	Name of the task.
TaskItemStatusId	Guid?	Status of the task (foreign key to status definition).
ContactId	Guid?	Assigned contact (responsible person).
ProjectId	Guid?	Associated project.
PlanningId	Guid?	Linked planning element.
GroupId	Guid	Task group.
StartDateTime	DateTimeOffset?	Start date and time.
EndDateTime	DateTimeOffset?	End date and time.
IsDone	boolean	Indicates whether the task is completed.
DoneDate	DateTimeOffset?	Completion date (read-only, automatically set when IsDone changes).
WorkAmount	double	Work effort (hours).
CustomColor	int32?	Custom color (as integer value).
CardPositionNumber	int32	Position on the Kanban board.
DescriptionHTML	string?	Task description as HTML.
IsBillable	boolean	Indicates whether the task is billable.
Recurrence	int32	Recurrence pattern. Values: 0 = No recurrence, 1 = Daily, 2 = Monday to Friday, 3 = Weekly, 4 = Monthly, 5 = Yearly, 6 = Biweekly, 7 = Quarterly.
AssignedByContactId	Guid?	Contact who assigned the task.
CreatedByContactId	Guid	Contact who created the task.
ContactDisplayName	string?	Display name of the assigned contact (read-only).
ContactImageId	Guid?	Image ID of the assigned contact (read-only).
RiskId	Guid?	Linked risk.
RiskName	string?	Name of the linked risk (read-only).
ChecklistItemsCount	int32	Total number of checklist items.
CheckListItemsDoneCount	int32	Number of completed checklist items.
CheckListItemsOpenCount	int32	Number of open checklist items.
ContributorsCount	int32	Number of contributors.
ContributorsWorkAmount	double	Work effort of all contributors.
WorkAmountOwner	double	Work effort of the responsible person.

---

Endpoints

CRUD Operations

Retrieve all tasks

GET/odata/Task

Supports OData query parameters.

---

Retrieve a single task by its ID

GET/odata/Task({key})

Parameter	Type	Required	Description
key	Guid	✅	The TaskItemId of the task.

---

Create a new task

POST/odata/Task

Parameter	Type	Required	Description
Body	Delta<ApiTask>	✅	JSON object with the task properties.

---

Update a task

PATCH/odata/Task({key})

Parameter	Type	Required	Description
key	Guid	✅	The TaskItemId of the task.
Body	Delta<ApiTask>	✅	JSON object with the fields to update.

---

Delete a task

DELETE/odata/Task({key})

Parameter	Type	Required	Description
key	Guid	✅	The TaskItemId of the task to delete.

warning

Deleting a task cannot be undone.

---

Batch Processing

Create multiple tasks at once

POST/odata/Task/BatchInsert

Parameter	Type	Required	Description
Body	object	✅	JSON object with an array of task data.

---

Delete multiple tasks at once

POST/odata/Task/BatchDelete

Parameter	Type	Required	Description
Body	object	✅	JSON object with an array of TaskItemIds.

warning

Batch deletion permanently removes all specified tasks. This action cannot be undone.

Performance

Batch processing is significantly more efficient than creating or deleting tasks individually. Use BatchInsert and BatchDelete when working with large volumes.

---

Task Management

Move a task within the Kanban

POST/odata/Task({key})/MoveTaskItem

Parameter	Type	Required	Description
key	Guid	✅	The TaskItemId.
Body	object	✅	JSON object with the following fields: taskItemStatusId (Guid, required) — The ID of the target TaskItemStatus. afterTaskItemId (Guid?, optional) — The ID of the task to place this one after. If omitted or null, the default position is used.

---

Update a project-defined field of the task

POST/odata/Task({key})/UpdateProjectDefinedField

Parameter	Type	Required	Description
key	Guid	✅	The TaskItemId.
Body	object	✅	JSON object with the following fields: fieldName (string, required) — The name of the project-defined field (e.g. "pf_dt0_xxxxxxxx_SomeField"). value (string?, optional) — The value to set, or null to clear.

---

Duplicate a task

POST/odata/Task({key})/Copy

Parameter	Type	Required	Description
key	Guid	✅	The TaskItemId of the task to copy.
Body	object	✅	JSON object with the following fields: projectId (Guid?, optional) — Target project ID. If omitted or null, the copy remains in the same project as the source task.

---

Comments

The TaskItemNote entity is the underlying data model for task comments. Each comment is stored as a TaskItemNote and linked to a specific task.

Property	Type	Description
TaskItemNoteId	guid	Unique ID of the note.
TaskItemId	guid	ID of the associated task.
Note	string	Note text (plain text).
NoteHtml	string	Note text (HTML-formatted).
ShortDescription	string	Short description.
CreateDateTime	DateTimeOffset	Creation timestamp.
CreatedByContactId	guid	ID of the creator.

Retrieve all task comments across all tasks in the system

GET/odata/TaskItemNote

Supports OData query parameters.

Filter by a task:

GET /odata/TaskItemNote?$filter=TaskItemId eq xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&$orderby=CreateDateTime desc

---

Retrieve a task comment by ID

GET/odata/TaskItemNote({key})

Parameter	Type	Required	Description
key	guid	✅	The TaskItemNoteId.

---

Add a comment to the task

POST/odata/Task({key})/AddNote

Parameter	Type	Required	Description
key	Guid	✅	The TaskItemId.
Body	object	✅	JSON object with the following fields: htmlText (string, required) — HTML-formatted comment content. notificationContactIds (Guid[], required) — Contact IDs to be notified (can be empty []).

---

Delete a comment from the task

GET/odata/Task/DeleteNote(noteRelationId={noteRelationId})

Parameter	Type	Required	Description
noteRelationId	Guid	✅	The ID of the comment relation.

warning

Deleting a comment cannot be undone.

---

Contributors

Retrieve all contributors of a task

GET/odata/Task({key})/GetContributors()

Parameter	Type	Required	Description
key	Guid	✅	The TaskItemId.

---

Add a contributor

POST/odata/Task({key})/AddContributor

Parameter	Type	Required	Description
key	Guid	✅	The TaskItemId.
Body	object	✅	JSON object with the following fields: contactId (Guid, required) — The contact to add. workAmount (double, optional) — Work effort in hours. isDone (boolean, optional) — Completion status.

---

Update a contributor

POST/odata/Task({key})/UpdateContributor

Parameter	Type	Required	Description
key	Guid	✅	The TaskItemId.
Body	object	✅	JSON object with the following fields: id (Guid, required) — The ID of the contributor. workAmount (double, optional) — Work effort in hours. isDone (boolean, optional) — Completion status.

---

Remove a contributor

POST/odata/Task({key})/RemoveContributor

Parameter	Type	Required	Description
key	Guid	✅	The TaskItemId.
Body	object	✅	JSON object with the following fields: id (Guid, required) — The ID of the contributor to remove.

---

Stopwatch

Retrieve the current stopwatch status of a task

GET/odata/Task({key})/GetStopwatch()

Parameter	Type	Required	Description
key	Guid	✅	The TaskItemId.

---

Start the stopwatch

POST/odata/Task({key})/StartStopwatch

Parameter	Type	Required	Description
key	Guid	✅	The TaskItemId.

---

Pause the stopwatch

POST/odata/Task({key})/PauseStopwatch

Parameter	Type	Required	Description
key	Guid	✅	The TaskItemId.

---

Stop the stopwatch

POST/odata/Task({key})/StopStopwatch

Parameter	Type	Required	Description
key	Guid	✅	The TaskItemId.

Stopwatch Workflow

The typical workflow is: StartStopwatch → PauseStopwatch (optional) → StopStopwatch. When stopped, a time entry is automatically created.

---

Documents

Link a document to the task

POST/odata/Task({key})/AddDocumentToTaskItem

Parameter	Type	Required	Description
key	Guid	✅	The TaskItemId.
Body	object	✅	JSON object with the following fields: documentIds (Guid[], required) — Array of document IDs to link.

---

Remove a document from the task

POST/odata/Task({key})/RemoveDocumentFromTaskItem

Parameter	Type	Required	Description
key	Guid	✅	The TaskItemId.
Body	object	✅	JSON object with the following fields: documentId (Guid, required) — The document ID whose link should be removed.

---

Relations

Add a relation to the task

POST/odata/Task({key})/AddRelation

Parameter	Type	Required	Description
key	Guid	✅	The TaskItemId.
Body	object	✅	JSON object with the following fields: itemId (Guid, required) — The ID of the element to link.

---

Remove a relation from the task

POST/odata/Task({key})/RemoveRelation

Parameter	Type	Required	Description
key	Guid	✅	The TaskItemId.
Body	object	✅	JSON object with the following fields: itemId (Guid, required) — The ID of the element to remove.

---

Calendar Synchronization

Retrieve the calendar sync status of the task

GET/odata/Task({key})/GetCalendarSyncStatus()

Parameter	Type	Required	Description
key	Guid	✅	The TaskItemId.

---

Enable calendar sync for the task

POST/odata/Task({key})/EnableCalendarSync

Parameter	Type	Required	Description
key	Guid	✅	The TaskItemId.

---

Disable calendar sync for the task

POST/odata/Task({key})/DisableCalendarSync

Parameter	Type	Required	Description
key	Guid	✅	The TaskItemId.

---

Notifications / Followers

Retrieve all notification subscribers of the task

GET/odata/Task({key})/GetNotificationFollowerContacts()

Parameter	Type	Required	Description
key	Guid	✅	The TaskItemId.

---

Add notification subscribers to the task

POST/odata/Task({key})/AddNotificationFollowers

Parameter	Type	Required	Description
key	Guid	✅	The TaskItemId.
Body	object	✅	JSON object with the following fields: contactIds (Guid[], required) — Contact IDs to add as subscribers. projectId (Guid?, optional) — The project context.

---

Remove a notification subscriber

POST/odata/Task({key})/RemoveNotificationFollower

Parameter	Type	Required	Description
key	Guid	✅	The TaskItemId.
Body	object	✅	JSON object with the following fields: contactId (Guid, required) — The contact ID of the subscriber to remove.

---

TaskStatus

The TaskStatus entity defines the Kanban task status of a project. Each status can have a color and a sort position.

info

TaskStatus entries are project-specific. Each project can define its own set of task statuses.

Data Model

Property	Type	Description
TaskItemStatusId	guid	Unique ID of the task status.
Name	string	Name of the status.
ProjectId	guid	ID of the associated project.
OrdinalPosition	int	Sort position.
Color	int?	Color value (as integer).

Endpoints

Retrieve all task statuses

GET/odata/TaskStatus

To filter by the statuses of a project in the order of the Kanban board:

GET /odata/TaskStatus?$filter=ProjectId eq xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&$orderby=OrdinalPosition

---

Retrieve a task status by ID

GET/odata/TaskStatus({key})

Parameter	Type	Required	Description
key	guid	✅	The TaskItemStatusId.

---

Create a new task status

POST/odata/TaskStatus

Parameter	Type	Required	Description
Body	Delta<ApiTaskStatus>	✅	JSON object with the properties from the data model.

---

Update a task status

PATCH/odata/TaskStatus({key})

Parameter	Type	Required	Description
key	guid	✅	The TaskItemStatusId.
Body	Delta<ApiTaskStatus>	✅	JSON object with the fields to update.

---

Delete a task status

DELETE/odata/TaskStatus({key})

Parameter	Type	Required	Description
key	guid	✅	The TaskItemStatusId.

warning

Deleting a task status affects all tasks in the project that use it. This action cannot be undone.

Returns 204 No Content on success.

---

TaskItemTemplate

The TaskItemTemplate entity allows saving and loading task templates. Templates can capture task structures from existing projects and load them into other projects.

Data Model

Property	Type	Description
TaskItemTemplateId	guid	Unique ID of the template.
Name	string	Name of the template.

Endpoints

CRUD Operations

Retrieve all task templates

GET/odata/TaskItemTemplate

---

Retrieve a task template by ID

GET/odata/TaskItemTemplate({key})

Parameter	Type	Required	Description
key	guid	✅	The TaskItemTemplateId.

---

Create a new task template

POST/odata/TaskItemTemplate

Parameter	Type	Required	Description
Body	Delta<ApiTaskItemTemplate>	✅	JSON object with the properties from the data model.

---

Update a task template

PATCH/odata/TaskItemTemplate({key})

Parameter	Type	Required	Description
key	guid	✅	The TaskItemTemplateId.
Body	Delta<ApiTaskItemTemplate>	✅	JSON object with the fields to update.

---

Delete a task template

DELETE/odata/TaskItemTemplate({key})

Parameter	Type	Required	Description
key	guid	✅	The TaskItemTemplateId.

warning

Deleting a task template cannot be undone.

Returns 204 No Content on success.

Save a template from the tasks of a project

POST/odata/TaskItemTemplate/SaveTemplateForProject

Parameter	Type	Required	Description
Body	object	✅	JSON object with the following fields: ProjectId (guid, required) — The project whose task structure should be saved. Name (string, required) — Name of the new template.

Saves the tasks of an existing project as a reusable template.

---

Load a template into a project

POST/odata/TaskItemTemplate({key})/LoadTemplateForProject

Parameter	Type	Required	Description
key	guid	✅	The TaskItemTemplateId.
Body	object	✅	JSON object with the following fields: ProjectId (guid, required) — The target project.

Creates tasks in the specified project based on the template.

tip

When loading a template, the tasks are transferred into the target project.

---

Download a template

GET/odata/TaskItemTemplate({key})/DownloadTemplate()

Parameter	Type	Required	Description
key	guid	✅	The TaskItemTemplateId.

Returns a file with content type application/xml and the filename {TemplateName}.json.

---

DynamicTaskItem

The /odata/DynamicTaskItem endpoint provides a read-only, flattened view that merges data from task, project, planning, portfolio, and permissions. All properties are prefixed (e.g. TaskItem_Name, Project_Name, Planning_DisplayName). Custom fields follow the pattern CF_<FieldName>.

Retrieve flattened task list with project, planning, and permission data

GET/odata/DynamicTaskItem

Read-Only Access

DynamicTaskItem supports GET requests only. To create or edit, use the regular /odata/Task endpoints.

---

OData Query Examples

Retrieve open tasks of a project

GET /odata/Task?$filter=ProjectId eq 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' and IsDone eq false

Tasks of a specific contact

GET /odata/Task?$filter=ContactId eq 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'

Overdue tasks

GET /odata/Task?$filter=EndDateTime lt 2025-01-01T00:00:00Z and IsDone eq false

Create a task

POST /odata/Task
Content-Type: application/json

{
  "Name": "Test API integration",
  "ProjectId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "ContactId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "StartDateTime": "2025-02-01T09:00:00Z",
  "EndDateTime": "2025-02-15T17:00:00Z",
  "WorkAmount": 16.0
}

Mark a task as done

PATCH /odata/Task('xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx')
Content-Type: application/json

{
  "IsDone": true
}

Create multiple tasks at once

POST /odata/Task/BatchInsert
Content-Type: application/json

{
  "items": [
    { "Name": "Task 1", "ProjectId": "..." },
    { "Name": "Task 2", "ProjectId": "..." }
  ]
}

tip

Combine $filter with $select to minimize the payload size. For tasks, filtering by ProjectId and IsDone is the most common pattern.