Projects Resource

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

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

Project Properties

Project properties available via API:

Property	Description
id	Unique project identifier.
customerId	Unique parent (customer) identifier.
customerName	Name of project’s customer.
name	Project name.
archived	Project status. Possible values: true (archived), false (active).
created	Project creation date and time.
description	Project description.
url	Project 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 project. See the PATCH/projects/{id} and DELETE/projects/{id} methods to read more about required permissions for these actions.

Required Permissions

Project’s properties and comments can be retrieved by any user who can access the entire project or at least one of its tasks 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 projects 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 Project Properties

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

GET/projects/{id}

Also see the ‘Required Permissions’ section.

Example Request:

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

Example Response:

{
  "id": 13,
  "customerId": 7,
  "name": "Spaceship building",
  "archived": false,
  "created": 1566950400000,
  "url": "<your actiTIME URL>/tasks/tasklist.do?projectId=13",
  "customerName": "Galaxy Corporation",
  "allowedActions": {
    "canModify": true,
    "canDelete": true
  },
  "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 Projects

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

GET/projects

The request can be specified with several parameters:

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

Also see the ‘Required Permissions’ section.

Example Request:

curl -X GET "&ltactiTIME URL&gt/api/v1/projects?offset=0&limit=2&sort=%2Bcreated" -H "accept: application/json; charset=UTF-8" -u "username:password"

Example Response:

{
  "offset": 0,
  "limit": 2,
  "items": [
    {
      "id": 13,
      "customerId": 7,
      "name": "Spaceship building",
      "archived": false,
      "created": 1566950400000,
      "url": "<your actiTIME URL>/tasks/tasklist.do?projectId=13",
      "customerName": "Galaxy Corporation",
      "allowedActions": {
        "canModify": true,
        "canDelete": true
      },
      "description": null
    },
    {
      "id": 14,
      "customerId": 6,
      "name": "Spaceship testing",
      "archived": false,
      "created": 1566950400000,
      "url": "<your actiTIME URL>/tasks/tasklist.do?projectId=14",
      "customerName": "Big Bang Company",
      "allowedActions": {
        "canModify": true,
        "canDelete": true
      },
      "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 project with given ID:

GET/projects/{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/projects/19/comments?offset=0&limit=1000&includeReferenced=users" -H "accept: application/json; charset=UTF-8" -u "username:password"

Example Response:

{
  "offset": 0,
  "limit": 1000,
  "items": [
    {
      "id": 10,
      "userId": 1,
      "created": 1553252667000,
      "updated": null,
      "updatingUserId": null,
      "text": "great job"
    },
    {
      "id": 9,
      "userId": 16,
      "created": 1553252632000,
      "updated": null,
      "updatingUserId": null,
      "text": "project is completed."
    }
  ],
  "users": {
    "1": {
      "id": 1,
      "active": true,
      "firstName": "John",
      "middleName": "",
      "lastName": "Doe",
      "departmentId": 5,
      "timeZoneGroupId": -1,
      "fullName": "John Doe"
    },
    "16": {
      "id": 16,
      "active": true,
      "firstName": "Daniel",
      "middleName": "",
      "lastName": "Alvarez",
      "departmentId": 7,
      "timeZoneGroupId": 3,
      "fullName": "Daniel Alvarez"
    }
  }
}

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

Update Project Properties

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

PATCH/projects/{id}

Only the following properties can be updated: ‘customerId’, ‘name’, ‘archived’, and ‘description’.
Changing the ‘customerId’ property means moving the project to another customer.

Required Permissions

To be able to modify project’s properties, the user should have:

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

Please note:

1. The ‘customerId’ property of a project can be changed if only all of the following requirements are met as this operation is equal to moving the project:

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

2. The ‘archived’ property of a project cannot be changed from ‘true’ to ‘false’ if customer of the project is archived.

Example Request:

curl -X PATCH "&ltactiTIME URL&gt/api/v1/projects/17" -H "accept: application/json; charset=UTF-8" -H "Content-Type: application/json" -u "username:password" -d "{ \"customerId\": 7, \"name\": \"Android Testing\", \"archived\": false, \"description\": \"urgent\"}"

Example Response:

{
  "id": 17,
  "customerId": 7,
  "name": "Android Testing",
  "archived": false,
  "created": 1566950400000,
  "url": "<your actiTIME URL>/tasks/tasklist.do?projectId=17",
  "customerName": "Galaxy Corporation",
  "allowedActions": {
    "canModify": true,
    "canDelete": true
  },
  "description": "urgent"
}

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

Create Project

Use the following request to create a new project:

POST/projects

While creating a project, the following properties can be specified: ‘customerId’, ‘name’, ‘archived’, and ‘description’.
The ‘customerId’ and ‘name’ fields are mandatory, other fields are optional.

Required Permissions

To be able to create new projects in a target customer the user should have:

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

Entire Scope of Work,

Target Customer,

All Existing & Future Projects of Target Customer & Create New.

Example Request:

curl -X POST "&ltactiTIME URL&gt/api/v1/projects" -H "accept: application/json; charset=UTF-8" -H "Content-Type: application/json; charset=UTF-8" -u "username:password" -d "{ \"customerId\": 7, \"name\": \"Consulting\", \"archived\": false, \"description\": \"Meetings & Calls\"}"

Example Response:

{
  "id": 49,
  "customerId": 7,
  "name": "Consulting",
  "archived": false,
  "created": 1625499137000,
  "url": "<your actiTIME URL>/tasks/tasklist.do?projectId=49",
  "customerName": "Galaxy Corporation",
  "allowedActions": {
    "canModify": true,
    "canDelete": true
  },
  "description": "Meetings & Calls"
}

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

Delete Project

Use the following request to delete specific project with all its tasks (including all time tracked for it by users):

DELETE/projects/{id}

Additionally to the project 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 project the user should have:

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

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

if time-track of other users for the project’s tasks 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 project’s tasks 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/projects/25?revokeApprovedWeeks=false" -H "accept: application/json; charset=UTF-8" -u "username:password"

Example Response

The 204 status code is returned if the 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.cannot_delete_because_tt_locked",
  "message": "Cannot delete the object as it has locked time-track"
}

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

API Documentation

Projects Resource

Project Properties

Required Permissions

Retrieve Project Properties

Retrieve List of Projects

Retrieve List of Comments

Update Project Properties

Create Project

Delete Project