Time-Track Resource

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

GET/timetrack

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

Users’ time-track records that can be retrieved are defined by 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

Note that:

1. If a user has several permissions, available objects are summarized.
For example, a user with the ‘Enter Time-Track’ and the ‘Manage Scope of Work’ permissions can access 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 access time-track of any user in the system.

Retrieve Users’ Time-Track

Use the following request to extract users’ work time tracked for available tasks:

GET/timetrack/{id}

Use another request to retrieve leave time tracked by users:

GET/leavetime/{id}

The GET/timetrack/{id} request can be specified with several parameters:

Parameter Description
userIds If provided, only time-track of users with given IDs will be returned.
If not provided, time-track of all available users will be returned.
taskIds If provided, only time tracked for tasks with given IDs will be returned.
If not provided, time tracked for all available tasks will be returned.
projectIds If provided, only time tracked for all available tasks of projects with given IDs will be returned.
If not provided, time tracked for all available tasks will be returned.
customerIds If provided, only time tracked for all available tasks of customers with given IDs will be returned.
If not provided, time tracked for all available tasks will be returned.
dateFrom Required parameter.
Only time tracked after this date will be returned.
dateTo If provided, only time tracked before this date will be returned.
If not provided, all time tracked from [dateFrom] to 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 shown. Time records for remaining days are not included in the response.
includeReferenced Additional data that can also be included in the response:
– time-track comments;
– tasks properties;
– projects properties;
– customers properties;
– users properties;
– departments properties;
– time zone groups properties;
– types of work properties.

Example Request:

curl -X GET "<actiTIME URL>/api/v1/timetrack?userIds=1&taskIds=95&dateFrom=2019-03-01&stopAfter=1000&includeReferenced=comments%2Cusers%2Ctasks%2Cprojects%2Ccustomers" 
-H "accept: application/json; charset=UTF-8" 
-H "authorization: Basic YWRtaW46bWFuYWdlcg=="

Example Response

{
  "users": {
    "1": {
      "id": 1,
      "username": "admin",
      "active": true,
      "firstName": "John",
      "middleName": "",
      "lastName": "Doe",
      "departmentId": 5,
      "timeZoneGroupId": -1,
      "hired": "2018-11-28",
      "email": "demodata@actitime.com",
      "fullName": "John Doe"
    }
  },
  "dateFrom": "2019-03-01",
  "dateTo": "2019-03-05",
  "customers": {
    "6": {
      "id": 6,
      "name": "Big Bang Company",
      "archived": false,
      "created": 1543352400000,
      "description": "Building and testing a new generation spaceship"
    }
  },
  "projects": {
    "15": {
      "id": 15,
      "customerId": 6,
      "name": "Flight operations",
      "archived": false,
      "created": 1543352400000,
      "description": null
    }
  },
  "tasks": {
    "95": {
      "id": 95,
      "name": "NASA negotiations",
      "description": null,
      "created": 1543352400000,
      "status": "open",
      "workflowStatusId": 4,
      "customerId": 6,
      "projectId": 15,
      "typeOfWorkId": 15,
      "deadline": null,
      "estimatedTime": null
    }
  },
  "data": [
    {
      "userId": 1,
      "records": [
        {
          "taskId": 95,
          "time": 135,
          "comment": "lala"
        }
      ],
      "dayOffset": 3
    },
    {
      "userId": 1,
      "records": [
        {
          "taskId": 95,
          "time": 120
        }
      ],
      "dayOffset": 4
    }
  ]
}

Note that:

1. Users’ IDs are always included in the response in order to identify time-track records.

2. Time-track date is not provided directly in the response. Instead, the ‘dayOffset’ parameter is used. Time-Track 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 is included in 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 time-track records.

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