Time-Track Resource

The following requests are supported for the operations with the time-track records via actiTIME API:

GET/timetrack
GET/timetrack/{userId}/{date}/{taskId}
PATCH/timetrack/{userId}/{date}/{taskId}
PATCH/timetrack/{userId}/{date}/{taskId}/time
POST/timetrack/lock
POST/timetrack/unlock

Time-Track Record Properties

Time-track record properties available via API:

Property Description
taskId Unique identifier of the task the time is tracked for.
time Tracked time (in minutes).
comment Optional comment for the time-track record.

Required Permissions

  1. Users’ time-track records that can be retrieved are defined by the users and the tasks available to the authorized user under their permissions.
    Permission Available Users Available Tasks
    Enter Time-Track Authorized User Only Work Assignments
    Manage Accounts & Permissions All Users All Tasks
    Modify & Approve Users’ Time-Track Assigned Team Scope of Work
    Manage Scope of Work Assigned Team Scope of Work
    Manage Cost & Billing Data Assigned Team Scope of Work
  2. Users’ time-track records that can be modified are defined by the users and the tasks available to the authorized user under their permissions.
    Permission Available Users Available Tasks
    Enter Time-Track Authorized User Only Work Assignments
    Modify & Approve Users’ Time-Track with Manage Scope of Work Assigned Team Scope of Work
    Modify & Approve Users’ Time-Track without Manage Scope of Work Assigned Team Only the tasks from Scope of Work of the authorized user that are also included into Work Assignments of the team user.
  3. Users’ time-track that can be locked / unlocked are defined by the authorized user’s permissions:

    if the authorized user has the ‘Lock Time-Track For Any User’ permission, then they can lock / unlock all records (belonging to both working and leave time) of all users within the system. Otherwise, none of the time-track can be locked / unlocked by this user.

Notes:

  1. If a user has several permissions, the available objects are summarized.
    For example, a user with the ‘Enter Time-Track’ and the ‘Manage Scope of Work’ permissions can retrieve the time tracked for the user’s work assignments by the user themselves and their assigned team.
  2. If a user is included in the list of ‘Allow selected users to see all users’ data in reports, charts and task details tab’ setting (‘Data Access Restrictions’ section of General Settings interface), then this user can retrieve the time-track of any user in the system.

Retrieve Users’ Time-Track

Use one of the following requests to retrieve the users’ working time tracked for the available tasks:

GET/timetrack
GET/timetrack/{userId}/{date}/{taskId}

The GET/timetrack request allows you to get the time-track (working time) of all the users and the tasks available at the same time as well as get more specific time-track provided filtering parameters. Also related objects’ info can be included into the response.

The GET/timetrack request can be specified with the following parameters:

approvedIf ‘true’, then only the approved time-track will be returned, if ‘false’ – only not approved one.
If not provided, both approved and not approved time-track will be returned.
If the ‘Time-Track Approval’ feature is turned off, the data will not be filtered by approval status and the corresponding field will not be returned.

Parameter Description
userIds If provided, only the time-track of users with given IDs will be returned.
If not provided, the time-track of all available users will be returned.
taskIds If provided, only the time tracked for the tasks with given IDs will be returned.
If not provided, the time tracked for all available tasks will be returned.
projectIds If provided, only the time tracked for all available tasks of the projects with given IDs will be returned.
If not provided, the time tracked for all available tasks will be returned.
customerIds If provided, only the time tracked for all available tasks of the customers with given IDs will be returned.
If not provided, the time tracked for all available tasks will be returned.
dateFrom Required parameter.
Only the time tracked after this date will be returned.
dateTo If provided, only the time tracked before this date will be returned.
If not provided, all the time tracked from [dateFrom] to the last tracked date (with time-track) will be returned.
stopAfter If provided, n time-track records will be returned (approximately). The maximum value is 1000.
If not provided, the default value (1000) is applied.
The numbers are approximate because all available time-track records for each day are returned. When the ‘stopAfter’ limit is reached on a specific day, the entire time-track for that day is retrieved. Time records for the remaining days are not included into the response.
includeReferenced Additional data that can also be included into the response:
– [comments] time-track comments (if there is no comment for the record, the ‘comment’ field will not be returned);
– [approvalStatus] approval status;
– [tasks] tasks’ properties;
– [projects] projects’ properties;
– [customers] customers’ properties;
– [users] users’ properties;
– [departments] departments’ properties;
– [timeZoneGroups] time zone groups’ properties;
– [typesOfWork] types of work’s properties.

Example Request:

curl -X GET "<actiTIME URL>/api/v1/timetrack?userIds=1&dateFrom=2020-10-06&dateTo=2020-10-07&stopAfter=1000&includeReferenced=approvalStatus" -H "accept: application/json; charset=UTF-8" -u "username:password"

Example Response

{
    "dateFrom": "2020-10-06",
    "dateTo": "2020-10-07",
    "data": [{
            "userId": 1,
            "records": [{
                    "taskId": 95,
                    "time": 120
                },
                {
                    "taskId": 116,
                    "time": 150
                },
                {
                    "taskId": 135,
                    "time": 150
                },
                {
                    "taskId": 138,
                    "time": 90
                }
            ],
            "approved": false,
            "dayOffset": 0,
            "date": "2020-10-06"
        },
        {
            "userId": 1,
            "records": [{
                    "taskId": 135,
                    "time": 290
                },
                {
                    "taskId": 138,
                    "time": 210
                }
            ],
            "approved": false,
            "dayOffset": 1,
            "date": "2020-10-07"
        }
    ]
}

Notes:

  1. Users’ IDs are always included into the response in order to identify the time-track records.
  2. Time-track date is provided in the ‘date’ field of the response. Additionally, the ‘dayOffset’ parameter is used.
    ‘date’ = ‘dateFrom’ + ‘dayOffset’
  3. If customers’, projects’ and tasks’ IDs are specified in one request, the following priority order is applied: tasks, projects, customers.
  4. If the number of time-track records to be returned is more than has been specified in the ‘stopAfter’ parameter, then the ‘nextDateFrom’ parameter will be included into the response. Use the value of this parameter as the value for the ‘dateFrom’ parameter in the next request if you want to get all the time-track records.

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

The GET/timetrack/{userId}/{date}/{taskId} request allows you to get only the time-track of the specified user for the specified task on the specified date.

Note that:

  • {userId} – user’s id OR username;
  • {date} – date is specified in the following format: ‘YYYY-MM-DD’ OR ‘today’;
  • {taskId} – task’s id.

Example Request:

curl -X GET "<actiTIME URL>/api/v1/timetrack/14/2019-04-01/104" -H "accept: application/json; charset=UTF-8" -u "username:password"

Example Response:

{
    "taskId": 104,
    "time": 150
}

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

Modify Users’ Time-Track

Use one of the following requests to modify the users’ working time:

PATCH/timetrack/{userId}/{date}/{taskId}
PATCH/timetrack/{userId}/{date}/{taskId}/time

The PATCH/timetrack/{userId}/{date}/{taskId} request allows you to enter the working time or modify it by replacing the existing value with a specified one. You can also enter or modify a time-track comment using this request.

The ‘time’ (in minutes) and ‘comment’ values should be specified in the request body.
If the ‘time’ value is set to 0, then the time-track record will be deleted.

Note that:

  • {userId} – user’s id OR username;
  • {date} – date is specified in the following format: ‘YYYY-MM-DD’ OR ‘today’;
  • {taskId} – task’s id.

Example Request:

curl -X PATCH "<actiTIME URL>/api/v1/timetrack/18/2019-05-08/108" -H "accept: application/json; charset=UTF-8" -H "Content-Type: application/json" -u "username:password" -d "{\"time\": \"120\", \"comment\": \"completed the task\"}"

Example Response:

{
    "taskId": 108,
    "time": 120,
    "comment": "completed the task"
}

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

The PATCH/timetrack/{userId}/{date}/{taskId}/time request allows you to increase or decrease the tracked time. In order to do this, the ‘delta’ value (in minutes) must be provided in the request body. The ‘delta’ value is the difference between the desired record time and the existing one.

  • If the ‘delta’ is a positive number, then this value will be added to the existing time.
  • If the ‘delta’ is a negative number, then this value will be deducted from the existing time.
  • If the ‘delta’ is 0, then the existing value will not be changed.

Note that:

  • {userId} – user’s id OR username;
  • {date} – date is specified in the following format: ‘YYYY-MM-DD’ OR ‘today’;
  • {taskId} – task’s id.

Example Request:

curl -X PATCH "<actiTIME URL>/api/v1/timetrack/18/2019-05-08/108/time" -H "accept: application/json; charset=UTF-8" -H "Content-Type: application/json" -u "username:password" -d "{ \"delta\": -20}"

Example Response:

{
    "taskId": 108,
    "time": 100,
    "comment": "completed the task"
}

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

Lock Users’ Time-Track

Use the following request to lock the users’ time-track:

POST/timetrack/lock

The POST/timetrack/lock request allows you to lock both working and leave time of one or several users for the selected date range.

The ‘userIds’, ‘dateFrom’ and ‘dateTo’ filters should be specified in the request body. If the request is successful, the IDs of the users whose time-track records have been locked will be returned in the response.

Note that:

  • userIds – list of users’ IDs whose time-track will be locked. Optional field. If the field is missing in the request body, then ALL users’ time-track will be affected.
  • dateFrom – starting date of the period to be locked. Mandatory field. Format: ‘YYYY-MM-DD’.
  • dateTo – ending date of the period to be locked. Mandatory field. Format: ‘YYYY-MM-DD’.

Example Request:

curl - X POST "<actiTIME URL>/api/v1/timetrack/lock" - H "accept: application/json; charset=UTF-8" - H "Content-Type: application/json" -u "username:password" - d "{ \"userIds\": [1, 13 ], \"dateFrom\": \"2022-01-01\", \"dateTo\": \"2022-01-31\"}"

Example Response:

{
    "userIds": [
        1,
        13
    ]
}

Notes:

  1. If you need to lock just 1 day, then the value of the ‘dateFrom’ filter must be equal to the value of the ‘dateTo’ filter.
  2. If you need to lock ALL users’ time-track at once, do not include the ‘userIds’ filter into the request.

Example request for locking all the users’ time-track for 1 day:

curl - X POST "<actiTIME URL>/api/v1/timetrack/lock" - H "accept: application/json; charset=UTF-8" - H "Content-Type: application/json" -u "username:password" - d "{\"dateFrom\": \"2022-02-01\", \"dateTo\": \"2022-02-01\"}"

Unlock Users’ Time-Track

Use the following request to unlock the users’ time-track:

POST/timetrack/unlock

The POST/timetrack/unlock request allows you to unlock both working and leave time of one or several users for the selected date range.

The ‘userIds’, ‘dateFrom’ and ‘dateTo’ filters should be specified in the request body. If the request is successful, the IDs of the users whose time-track records have been unlocked will be returned into the response.

Note that:

  • userIds – list of users’ IDs whose time-track will be unlocked. Optional field. If the field is missing in the request body, then ALL users’ time-track will be affected.
  • dateFrom – starting date of the period to be unlocked. Mandatory field. Format: ‘YYYY-MM-DD’.
  • dateTo – ending date of the period to be unlocked. Mandatory field. Format: ‘YYYY-MM-DD’.

Example Request:

curl - X POST "<actiTIME URL>/api/v1/timetrack/unlock" - H "accept: application/json; charset=UTF-8" - H "Content-Type: application/json" -u "username:password" - d "{ \"userIds\": [1, 13 ], \"dateFrom\": \"2022-01-01\", \"dateTo\": \"2022-01-31\"}"

Example Response:

{
    "userIds": [
        1,
        13
    ]
}

Notes:

  1. If you need to unlock just 1 day, then the value of the ‘dateFrom’ filter must be equal to the value of the ‘dateTo’ filter.
  2. If you need to unlock ALL users’ time-track at once, do not include the ‘userIds’ filter into the request.

Example request for unlocking all the users’ time-track for 1 day:

curl - X POST "<actiTIME URL>/api/v1/timetrack/unlock" - H "accept: application/json; charset=UTF-8" - H "Content-Type: application/json" -u "username:password" - d "{\"dateFrom\": \"2022-02-01\", \"dateTo\": \"2022-02-01\"}"