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,

or

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,

or

Target Customer,

or

All Existing & Future Projects of Target Customer,

or

Target Project,

or

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