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.
name Project name.
archived Project status. Possible values: true (archived), false (active).
created Project creation date and time.
description Project description.

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,

or

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 "<actiTIME URL>/api/v1/projects/13" 
-H "accept: application/json; charset=UTF-8" 
-H "authorization: Basic YWRtaW46bWFuYWdlcg=="

Example Response:

{
  "id": 13,
  "customerId": 6,
  "name": "Spaceship building",
  "archived": false,
  "created": 1543957200000,
  "allowedActions": {
    "canModify": true,
    "canDelete": true
  },
  "description": null
}

More info on using this request is available in our detailed documentation

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 "<actiTIME URL>/api/v1/projects?offset=0&limit=2&customer=6&sort=%2Bcreated&includeReferenced=customers" 
-H "accept: application/json; charset=UTF-8" 
-H "authorization: Basic YWRtaW46bWFuYWdlcg=="

Example Response:

{
  "offset": 0,
  "limit": 2,
  "items": [
    {
      "id": 13,
      "customerId": 6,
      "name": "Spaceship building",
      "archived": false,
      "created": 1543957200000,
      "allowedActions": {
        "canModify": true,
        "canDelete": true
      },
      "description": null
    },
    {
      "id": 14,
      "customerId": 6,
      "name": "Spaceship testing",
      "archived": false,
      "created": 1543957200000,
      "allowedActions": {
        "canModify": true,
        "canDelete": true
      },
      "description": null
    }
  ],
  "customers": {
    "6": {
      "id": 6,
      "name": "Big Bang Company",
      "archived": false,
      "created": 1543957200000,
      "description": "Building and testing a new generation spaceship"
    }
  }
}

More info on using this request is available in our detailed documentation

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 "<actiTIME URL>/api/v1/projects/19/comments?offset=0&limit=1000&includeReferenced=users" 
-H "accept: application/json; charset=UTF-8" 
-H "authorization: Basic YWRtaW46bWFuYWdlcg=="

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 our detailed documentation

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 "<actiTIME URL>/api/v1/projects/17" 
-H "accept: application/json; charset=UTF-8" 
-H "authorization: Basic YWRtaW46bWFuYWdlcg==" 
-H "Content-Type: application/json" -d "{ \"customerId\": 7, \"name\": \"Android Testing\", \"archived\": false, \"description\": \"urgent\"}"

Example Response:

{
  "id": 17,
  "customerId": 7,
  "name": "Android Testing",
  "archived": false,
  "created": 1543957200000,
  "allowedActions": {
    "canModify": true,
    "canDelete": true
  },
  "description": "urgent"
}

More info on using this request is available in our detailed documentation

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’.
‘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,

or

Target Customer,

or

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

Example Request:

curl -X POST "<actiTIME URL>/api/v1/projects" 
-H "accept: application/json; charset=UTF-8" 
-H "authorization: Basic YWRtaW46bWFuYWdlcg==" 
-H "Content-Type: application/json; charset=UTF-8" -d "{ \"customerId\": 7, \"name\": \"Consulting\", \"archived\": false, \"description\": \"Meetings & Calls\"}"

Example Response:

{
  "id": 24,
  "customerId": 7,
  "name": "Consulting",
  "archived": false,
  "created": 1552396621342,
  "allowedActions": {
    "canModify": true,
    "canDelete": true
  },
  "description": "Meetings & Calls"
}

More info on using this request is available in our detailed documentation

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 "<actiTIME URL>/api/v1/projects/25?revokeApprovedWeeks=false" 
-H "accept: application/json; charset=UTF-8" 
-H "authorization: Basic YWRtaW46bWFuYWdlcg=="

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 our detailed documentation