Tasks Resource

The following requests are supported for operations with tasks via actiTIME API:

GET/tasks/{id}
GET/tasks
GET/tasks/{id}/comments
PATCH/tasks/{id}
POST/tasks
DELETE/tasks/{id}

Task Properties

Task properties available via API:

Property	Description
id	Unique task identifier.
name	Task name.
description	Task description.
created	Task creation date and time.
customerId	Unique parent identifier (customer identifier).
customerName	Name of task’s customer.
projectId	Unique parent identifier (project identifier).
projectName	Name of task’s project.
status	Task status. Possible values: open, completed.
workflowStatusId	Unique identifier of task’s workflow status.
workflowStatusName	Name of task’s workflow status.
typeOfWorkId	Unique identifier of task’s type of work.
typeOfWorkName	Name of task’s type of work.
deadline	Task’s deadline date.
estimatedTime	Task’s estimate (in minutes).
url	Task URL.

Alongside with the properties listed above, the ‘allowedActions’ property is also returned. The ‘allowedActions’ property shows whether the user can modify or delete this task. See the PATCH/tasks/{id} and DELETE/tasks/{id} methods to read more about required permissions for these actions.

Required Permissions

Task’s properties and comments can be retrieved by any user who can access the task in:

Work Assignments, which allows to enter time-track for tasks and requires the “Enter Time-Track” permission,

Scope of Work, which allows to manage the entity and is granted under the following permissions:

Manage Accounts & Permissions (all tasks belong to scope of work);
Modify & Approve Other Users’ Time-Track;
Manage Scope of Work;
Manage Cost & Billing Data.

Read more on available actions under various permissions in the User Guide.

Retrieve Task Properties

Use the following request to retrieve all properties of the task with the given ID:

GET/tasks/{id}

Also see the ‘Required Permissions’ section.

Example Request:

curl -X GET "&ltactiTIME URL&gt/api/v1/tasks/80" -H "accept: application/json; charset=UTF-8" -u "username:password"

Example Response:

{
  "id": 80,
  "name": "Product documentation",
  "description": null,
  "created": 1566950400000,
  "status": "open",
  "workflowStatusId": 4,
  "typeOfWorkId": 2,
  "url": "https://demo.actitime.com/tasks/tasklist.do?taskId=80",
  "projectName": "Spaceship building",
  "customerName": "Galaxy Corporation",
  "workflowStatusName": "In Progress",
  "typeOfWorkName": "non-billable",
  "allowedActions": {
    "canModify": true,
    "canDelete": true
  },
  "deadline": "2021-07-19",
  "estimatedTime": 3000,
  "customerId": 7,
  "projectId": 13
}

More info on using this request is available in Swagger at the following URL:
<your actiTIME URL>/api/v1/swagger

Retrieve List of Tasks

Use the following request to retrieve a list of available tasks with all their properties:

GET/tasks

The request can be specified with several parameters:

Parameter	Description
offset	Pagination offset. If provided, first n tasks will be not shown in the list.
limit	Pagination limit. If provided, the number of returned tasks will be limited to n. If not provided, the default value (1000) is used.
ids	If provided, only tasks with given IDs will be returned.
customerIds	If provided, only tasks of the customers with given IDs will be returned.
projectIds	If provided, only tasks of the projects with given IDs will be returned.
typeOfWorkIds	If provided, only tasks with types of work with given IDs will be returned.
workflowStatusIds	If provided, only tasks with workflow statuses with given IDs will be returned.
sort	Sets sorting of the results. Tasks can be sorted by creation date, name, and status.
name	If provided, only tasks with exact name match will be returned.
words	If provided, only tasks containing all given words in their names will be returned.
status	If provided, only open or only completed tasks will be returned. If not provided, both open and completed tasks will be returned.
includeReferenced	Additional data that can also be included in the response: – customers’ properties; – projects’ properties; – types of work properties; – workflow statuses properties.

Also see the ‘Required Permissions’ section.

Example Request:

curl -X GET "&ltactiTIME URL&gt/api/v1/tasks?offset=5&limit=2&sort=%2Bname&includeReferenced=customers" -H "accept: application/json; charset=UTF-8" -u "username:password"

Example Response:

{
  "offset": 5,
  "limit": 2,
  "items": [
    {
      "id": 142,
      "name": "Accounting",
      "description": "",
      "created": 1584621400000,
      "status": "open",
      "workflowStatusId": 1,
      "typeOfWorkId": 1,
      "url": "https://demo.actitime.com/tasks/tasklist.do?taskId=142",
      "projectName": "Accounting",
      "customerName": "Our company",
      "workflowStatusName": "New",
      "typeOfWorkName": "engineering",
      "allowedActions": {
        "canModify": true,
        "canDelete": true
      },
      "deadline": null,
      "estimatedTime": null,
      "customerId": 9,
      "projectId": 19
    },
    {
      "id": 103,
      "name": "Android calibration",
      "description": "",
      "created": 1566950400000,
      "status": "open",
      "workflowStatusId": 1,
      "typeOfWorkId": 1,
      "url": "https://demo.actitime.com/tasks/tasklist.do?taskId=103",
      "projectName": "Android prototyping",
      "customerName": "Galaxy Corporation",
      "workflowStatusName": "New",
      "typeOfWorkName": "engineering",
      "allowedActions": {
        "canModify": true,
        "canDelete": true
      },
      "deadline": "2019-12-27",
      "estimatedTime": 20400,
      "customerId": 7,
      "projectId": 16
    }
  ],
  "customers": {
    "7": {
      "id": 7,
      "name": "Galaxy Corporation",
      "archived": false,
      "created": 1566950400000,
      "url": "https://demo.actitime.com/tasks/tasklist.do?customerId=7",
      "description": null
    },
    "9": {
      "id": 9,
      "name": "Our company",
      "archived": false,
      "created": 1566950400000,
      "url": "https://demo.actitime.com/tasks/tasklist.do?customerId=9",
      "description": null
    }
  }
}

More info on using this request is available in Swagger at the following URL:
<your actiTIME URL>/api/v1/swagger

Retrieve List of Comments

Use the following request to retrieve a list of comments on the task with given ID:

GET/tasks/{id}/comments

The request can be specified with several parameters:

Parameter	Description
offset	Pagination offset. If provided, the first n comments will be not shown in the list.
limit	Pagination limit. If provided, the number of returned comments will be limited to n. If not provided, the default value (1000) is used.
includeReferenced	Additional data that can also be included in the response: – users that left the comments.

Example Request:

curl -X GET "&ltactiTIME URL&gt/api/v1/tasks/103/comments?offset=1&includeReferenced=users" -H "accept: application/json; charset=UTF-8" -u "username:password"

Example Response:

{
  "offset": 1,
  "limit": 1000,
  "items": [
    {
      "id": 3,
      "userId": 17,
      "created": 1552059104000,
      "updated": null,
      "updatingUserId": null,
      "text": "I spent a bit more time than expected"
    }
  ],
  "users": {
    "17": {
      "id": 17,
      "active": true,
      "firstName": "Brett",
      "middleName": "",
      "lastName": "Smith",
      "departmentId": 7,
      "timeZoneGroupId": -1,
      "fullName": "Brett Smith"
    }
  }
}

More info on using this request is available in Swagger at the following URL:
<your actiTIME URL>/api/v1/swagger

Update Task Properties

Use the following request to update the properties of the task with given ID:

PATCH/tasks/{id}

Only the following properties can be updated: ‘name’, ‘description’, ‘status’, ‘workflowStatusId’, ‘projectId’, ‘typeOfWorkId’, ‘deadline’, and ‘estimatedTime’.
Changing the ‘projectId’ property means moving the task to another project.

If you want to update the task’s status, please specify either ‘status’ property (the first workflow status of the “open” or “completed” group is applied) or ‘workflowStatusId’ property (the task will be automatically moved to the specified status’ group). Don’t specify both properties in one request.

The ‘status’ property of a task cannot be changed from ‘completed’ to ‘open’ if task’s project is archived. The same applies to the ‘workflowStatusId’ property if changing it implies moving the task between ‘open’ and ‘completed’ groups.

Required Permissions

To be able to modify a task, the user should have:

the ‘Manage Scope of Work’ permission;
access to the task in Scope of Work.

Also note that the ‘projectId’ property of a task can be changed if only all of the following requirements are met, as this operation is equal to moving the task to another project:

user has the ‘Manage Scope of Work’ permission.
user has access to the task in Scope of Work;
user is able to create new tasks in the target project.

Example Request:

curl -X PATCH "&ltactiTIME URL&gt/api/v1/tasks/84" -H "accept: application/json; charset=UTF-8" -H "Content-Type: application/json" -u "username:password" -d "{ \"name\": \"Building\", \"description\": \"building a rocketship\", \"workflowStatusId\": 3, \"projectId\": 17, \"typeOfWorkId\": 1, \"deadline\": \"2019-04-12T16:31:39.951Z\", \"estimatedTime\": 480}"

Example Response:

{
  "id": 84,
  "name": "Building",
  "description": "building a rocketship",
  "created": 1543957200000,
  "status": "open",
  "workflowStatusId": 3,
  "customerId": 7,
  "projectId": 17,
  "typeOfWorkId": 1,
  "url": "https://demo.actitime.com/tasks/tasklist.do?taskId=84",
  "projectName": "Android testing",
  "customerName": "Galaxy Corporation",
  "workflowStatusName": "Planning",
  "typeOfWorkName": "repair: complex",
  "allowedActions": {
    "canModify": true,
    "canDelete": true
  },
  "deadline": "2019-04-12",
  "estimatedTime": 480
}

More info on using this request is available in Swagger at the following URL:
<your actiTIME URL>/api/v1/swagger

Create Task

Use the following request to create a new task:

POST/tasks

While creating a task, the following properties can be specified: ‘name’, ‘description’, ‘status’, ‘workflowStatusId’, ‘projectId’, ‘typeOfWorkId’, ‘deadline’, and ‘estimatedTime’.
The ‘projectId’ and ‘name’ properties are mandatory, other fields are optional.

Required Permissions

To be able to create new tasks in a target project, a user should have:

the ‘Manage Scope of Work’ permission;
access to Scope of Work configured as follows:

Entire Scope,

Target Customer,

All Existing & Future Projects of Target Customer,

Target Project,

All Existing & Future Tasks of Target Project & Create New.

Example Request:

curl -X POST "&ltactiTIME URL&gt/api/v1/tasks" -H "accept: application/json; charset=UTF-8" -H "Content-Type: application/json; charset=UTF-8" -u "username:password" -d "{ \"name\": \"Calls\", \"description\": \"support\", \"status\": \"open\", \"projectId\": 16, \"typeOfWorkId\": 2, \"estimatedTime\": 120}"

Example Response:

{
  "id": 191,
  "name": "Calls",
  "description": "support",
  "created": 1625490199000,
  "status": "open",
  "workflowStatusId": 1,
  "typeOfWorkId": 2,
  "url": "https://demo.actitime.com/tasks/tasklist.do?taskId=191",
  "projectName": "Android prototyping",
  "customerName": "Galaxy Corporation",
  "workflowStatusName": "New",
  "typeOfWorkName": "non-billable",
  "allowedActions": {
    "canModify": true,
    "canDelete": true
  },
  "deadline": null,
  "estimatedTime": 120,
  "customerId": 7,
  "projectId": 16
}

More info on using this request is available in Swagger at the following URL:
<your actiTIME URL>/api/v1/swagger

Delete Task

Use the following request to delete a specific task including all time tracked for it by users:

DELETE/tasks/{id}

Additionally to the task ID, the request can include the ‘revokeApprovedWeeks’ parameter that defines how weeks’ approval statuses should be affected by deletion. Time-track approval for affected weeks can be kept or revoked.

Required Permissions

To be able to delete a task the user should have:

the ‘Manage Scope of Work’ permission;
access to this task in Scope of Work.

The authorized user also needs permissions that allow them to delete all time tracked for the task. This means that the following restrictions are additionally applied:

if time-track of other users for the task needs to be deleted, the authorized user should have the ‘Modify & Approve Other Users’ Time-Track’ permission and have these users in assigned team;
if time-track for the task on locked days needs to be deleted, the authorized user should have the ‘Lock Time-Track for Any User’ permission.

Example Request:

curl -X DELETE "&ltactiTIME URL&gt/api/v1/tasks/83?revokeApprovedWeeks=false" -H "accept: application/json; charset=UTF-8" -u "username:password"

Example Response

The 204 status code is returned if operation is successful. Response body is empty.

If the operation has failed, an error code is returned.

For example, the 403 error code is returned when the operation has failed due to the lack of a necessary permission:

{
  "key": "api.error.security_check.assigned_task",
  "message": "No access to task with given id"
}

More info on using this request is available in Swagger at the following URL:
<your actiTIME URL>/api/v1/swagger

API Documentation

Tasks Resource

Task Properties

Required Permissions

Retrieve Task Properties

Retrieve List of Tasks

Retrieve List of Comments

Update Task Properties

Create Task

Delete Task