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,
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" -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 "<actiTIME URL>/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 "<actiTIME URL>/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 "<actiTIME URL>/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,
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 "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 "<actiTIME URL>/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