Leave Time Resource

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

GET/leavetime
PATCH/leavetime/{userId}/{date}/{leaveTypeId}
PATCH/leavetime/{userId}/{date}/{leaveTypeId}/time

Leave Record Properties

Leave record properties available via API:

Property Description
userId Unique identifier of the user who tracked leave time.
leaveTypeId Unique identifier of the leave type.
leaveTime Duration of leave time record (in minutes).

Required Permissions

Users’ leave time records that can be retrieved are defined by the authorized user’s permissions.

Permission Available Users
Enter Time-Track Authorized User Only
Manage PTO & Sick Days Settings All Users
Manage Accounts & Permissions All Users
Modify & Approve Users’ Time-Track Assigned Team

Note that if a user has several permissions, available objects are summarized.
For example, a user with the ‘Enter Time-Track’ and ‘Modify & Approve Users’ Time-Track’ permissions can access leave time tracked by the user and the user’s assigned team.

Retrieve Users’ Leave Time

Use the following request to extract users’ leave time tracked by users:

GET/leavetime

Use another requests to retrieve work time tracked by users for tasks:

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

The GET/leavetime request can be specified with several parameters:

Parameter Description
userIds If provided, only leave time of users with given IDs will be returned.
If not provided, all available users’ leave time will be returned.
leaveTypeIds If provided, only leave time tracked for leave types with given IDs will be returned.
If not provided, leave time tracked for all leave types in the system will be returned.
dateFrom Required parameter.
Only leave time tracked after this date will be returned.
dateTo If provided, only leave time tracked before this date will be returned.
If not provided, all leave time tracked from [dateFrom] to last tracked date (with leave time) will be returned.
stopAfter If provided, n leave time 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 leave time records for each day are returned. When the ‘stopAfter’ limit is reached on a specific day, all leave time logged by requested users for that day is shown. Leave time records for remaining days are not included in the response.
includeReferenced Additional data that can also be included in the response:
– users properties;
– departments properties;
– time zone groups properties;
– leave types properties.

Example Request:

curl -X GET "&ltactiTIME URL&gt/api/v1/leavetime?userIds=1&dateFrom=2020-10-01&dateTo=2020-10-07&stopAfter=1000&includeReferenced=leaveTypes" -H "accept: application/json; charset=UTF-8" -u "username:password"

Example Response:

{
  "dateFrom": "2020-10-01",
  "dateTo": "2020-10-05",
  "leaveTypes": {
    "2": {
      "id": 2,
      "name": "Time Off",
      "balance": "PTO",
      "archived": false
    }
  },
  "data": [
    {
      "userId": 1,
      "dayOffset": 4,
      "date": "2020-10-05",
      "leaveTypeId": 2,
      "leaveTime": 120
    }
  ]
}

Note that:

1. Leave time date is provided in the ‘date’ field of the response. Additionally, the ‘dayOffset’ parameter is used.
‘date’ = ‘dateFrom’ + ‘dayOffset’

2. If the number of leave time 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 leave time records.

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

Modify Users’ Leave Time

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

PATCH/leavetime/{userId}/{date}/{leaveTypeId}
PATCH/leavetime/{userId}/{date}/{leaveTypeId}/time

The PATCH/leavetime/{userId}/{date}/{leaveTypeId} request allows you to enter leave time or modify it by replacing the existing value with a specified one.

The ‘leaveTime’ (in minutes) value must be specified in the request body.
If the ‘leaveTime’ value is set to 0, then the leave time record will be deleted.

Note that:

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

Example Request:

curl -X PATCH "<actiTIME URL>/api/v1/leavetime/1/today/3" -H "accept: application/json; charset=UTF-8" -H "Content-Type: application/json"  -u "username:password" -d "{ \"leaveTime\": 240}"

Example Response:

{
  "userId": 1,
  "dayOffset": 0,
  "date": "2021-07-05",
  "leaveTypeId": 3,
  "leaveTime": 240
}

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

The PATCH/leavetime/{userId}/{date}/{leaveTypeId}/time request allows you to increase or decrease leave 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 wishing record time and the existing one.

  • If the ‘delta’ is positive number, then this value will be added to the existing time.
  • If the ‘delta’ is 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’;
  • {leaveTypeId} – leave type’s id.

Example Request:

curl -X PATCH "<actiTIME URL>/api/v1/leavetime/1/2021-07-05/2/time" -H "accept: application/json; charset=UTF-8" -H "Content-Type: application/json"  -u "username:password" -d "{ \"delta\": 120}"

Example Response:

{
  "userId": 1,
  "dayOffset": 0,
  "date": "2021-07-05",
  "leaveTypeId": 2,
  "leaveTime": 240
}

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