Cost of Work Rates Resource
You can submit the following requests for operations with users’ cost of work rates in actiTIME API:
GET/userRates
GET/userRates/{uid}
PUT/userRates/{uid}
Cost of Work Rates Properties
| Property | Description |
|---|---|
| dateFrom | The date a rate is set and activated on (“Effective from” date in actiTIME). |
| regularRate | Regular work rate in actiTIME as a numeric value. |
| overtimeRate | Overtime rate in actiTIME as a numeric value. |
| leaveRates | Leave rates in actiTIME. |
| leaveTypeId | Unique leave type identifier. |
| rate | Leave rate as a numeric value. |
Required Permissions
In order to work with the GET endpoints, you need at least one of the following user permissions:
| Permission | Available Users |
|---|---|
| Manage Accounts & Permissions | All users |
| Manage Cost & Billing Data | Users from the assigned team |
To work with the PUT endpoint, you need the following permission:
| Permission | Available Users |
|---|---|
| Manage Accounts & Permissions | All users |
Note:
At this moment, API requests always process data on all three types of cost of work rates (i.e., regular rate, leave rate, and overtime rate), no matter if their corresponding functionality (i.e., Cost of Work Rates, Leave Time Tracking, and Overtime Registration) is activated or deactivated in your actiTIME account.
In other words, GET requests will invariably provide you with data on each type of cost of work rates, and PUT requests will allow you to change data for these rates even if their respective features are switched off in the system.
Besides, users’ individual overtime settings cannot be considered in API requests.
Retrieve Cost of Work Rates Properties for All / Selected Users
This request allows you to retrieve data for cost of work rates of all or selected users:
GET/userRates
You can specify this request using the following parameters:
| Parameter | Description |
|---|---|
| offset | Pagination offset that lets you exclude the indicated number of users from the response. The value of 0 is set by default. |
| limit | Pagination limit that allows you to narrow down the number of users in the response. The value of 1000 is set by default. |
| userIds | Filter by user ID, which lets you retrieve data for specific users only. You can set several user IDs for this parameter using a comma-separated list. |
| dateFrom | Filter by activation date. It allows you to retrieve data only for those cost of work rates that were active on a specified date or later. |
| department | Filter by user departments, which lets you retrieve data for specific work departments only. You can set several department IDs for this parameter using a comma-separated list. |
| timeZoneGroup | Filter by time zone groups, which lets you retrieve data for specific time zones only. You can set several time zone IDs for this parameter using a comma-separated list. |
| active | Filter by users’ account status, which can be active (True) or archived (False). |
Request Example
curl -X GET "<actiTIME URL>/api/v1/userRates?offset=0&limit=1000&active=true" -H "accept: application/json; charset=UTF-8" -u "username:password"
Response Example
{
"offset": 0,
"limit": 1000,
"items": [
{
"userId": 1,
"rates": [
{
"dateFrom": "2023-01-04",
"regularRate": 45,
"overtimeRate": 67.5,
"leaveRates": [
{
"leaveTypeId": 2,
"rate": 45
},
{
"leaveTypeId": 3,
"rate": 45
}
]
},
{
"dateFrom": "2023-03-01",
"regularRate": 50,
"overtimeRate": 70,
"leaveRates": [
{
"leaveTypeId": 2,
"rate": 50
},
{
"leaveTypeId": 3,
"rate": 50
}
]
}
]
},
{
"userId": 16,
"rates": [
{
"dateFrom": "2023-04-01",
"regularRate": 10,
"overtimeRate": 20,
"leaveRates": [
{
"leaveTypeId": 2,
"rate": 15
},
{
"leaveTypeId": 3,
"rate": 15
}
]
}
]
}
]
}
Notes:
- Request results are first sorted by user ID and then by dateFrom. You cannot change the sorting order via request parameters.
- Cost of work rates for both active and archived leave types are included in the response. You don’t have the option to filter the request by active leave types alone.
- To find out which cost of work rates are active on a specific date, you need to make the GET/userRates request with the required dateFrom value. The response will contain a list of all or selected users’ cost of work rates that were effective on the indicated date or later. Then, you can loop through all the users on the list to locate the first cost of work rate for each of them. See the example of a loop that can be used for this purpose in the function below.
Function Example
function getEffectiveUserRates (allUserRates) {
return allUserRates.items.map(item => ({
userId: item.userId,
rates: item.rates[0] ?? null
}))
}
In the above function, allUserRates is the result of the GET/userRates request with the required dateFrom value. It retrieves data on cost of work rates of all / selected users.
Function Result Example
[
{
"userId": 1,
"rates": {
"dateFrom": "2023-03-26",
"regularRate": 10,
"overtimeRate": 12,
"leaveRates": [
{
"leaveTypeId": 1,
"rate": 15
}
]
}
},
{
"userId": 2,
"rates": {
"dateFrom": "2023-03-17",
"regularRate": 10,
"overtimeRate": 15,
"leaveRates": [
{
"leaveTypeId": 1,
"rate": 20
}
]
}
}
]
Retrieve Cost of Work Rate Properties for a Single User
Use the following request to get data for cost of work rates of a single user:
GET/userRates/{uid}
Request Example
curl -X GET "<actiTIME URL>/api/v1/userRates/1" -H "accept: application/json; charset=UTF-8" -u "username:password"
Response Example
[
{
"dateFrom": "2023-01-04",
"regularRate": 45,
"overtimeRate": 67.5,
"leaveRates": [
{
"leaveTypeId": 2,
"rate": 45
},
{
"leaveTypeId": 3,
"rate": 45
}
]
},
{
"dateFrom": "2023-02-01",
"regularRate": 60,
"overtimeRate": 65,
"leaveRates": [
{
"leaveTypeId": 2,
"rate": 60
},
{
"leaveTypeId": 3,
"rate": 60
}
]
}
]
Notes:
- Request results are sorted by dateFrom. You cannot change the sorting order via request parameters.
- Cost of work rates for both active and archived leave types are included in the response.
- If you want to retrieve the cost of work rates for a specific date, submit the GET/userRates/{uid} request to get a list of a user’s cost of work rates. Then, process the received result using a loop like in the example below.
Function Example
function findUserEffectiveRates(date, allUserRates) {
for (let i = allUserRates.length - 1; i >= 0; i--)
if (allUserRates[i].dateFrom <= date)
return allUserRates[i]
return null
}
The above function has the following parameters:
- date set in the YYYY-MM-DD format;
- allUserRates – a user’s cost of work rates retrieved via GET/userRates/{uid} request.
Its result is a list of a user’s cost of work rates that were effective on a specific date (or “null” in case there were no such rates).
Function Result Example
{
"dateFrom": "2023-03-26",
"regularRate": 10,
"overtimeRate": 12,
"leaveRates": [
{
"leaveTypeId": 1,
"rate": 15
}
]
}
Modify Cost of Work Rates
Apply this request to delete, modify, or create data for cost of work rates:
PUT/userRates/{uid}
Notes:
- PUT request COMPLETELY RENEWS a selected user’s cost of work data in the system. In other words, it first deletes the already set data and then replaces it with values you indicate in the request body. THIS OPERATION CANNOT BE REVOKED, so you need to make PUT requests with extra care.
- The overtimeRate and leaveRate properties are optional and can be omitted from your request – in this case, a user’s rate will be replaced with a value in line with the default coefficient you’ve set in actiTIME.
Body Template:
[
{
"dateFrom": "[ISO date]",
"regularRate": [JSON number],
"overtimeRate": [JSON number],
"leaveRates": [
{
"leaveTypeId": [JSON number],
"rate": [JSON number]
},
{
"leaveTypeId": [JSON number],
"rate": [JSON number]
}
}
]
Mandatory properties in this example are:
- dateFrom (date in ISO format)
- regularRate (regular cost of work rate in actiTIME from 0 to 99999999)
Optional properties in the above example include:
- overtimeRate (overtime rate in actiTIME from 0 to 99999999)
- leaveRates:
- leaveTypeId (leave type ID in actiTIME)
- rate (leave rate in actiTIME from 0 to 99999999)
Thereby, the minimal version of the PUT request will look as follows:
Body Template with Minimal Input:
[
{
"dateFrom": "[ISO date]",
"regularRate": [JSON number]
}
]
Notes:
- PUT requests with a minimal set of properties contain merely an activation date (dateFrom) and a regular cost of work rate as a numeric value. Since optional parameters like overtime rate and leave rate are not specified in the body of such a request, actiTIME will set / edit them based on the default coefficients.
- For all three types of rates, you can indicate numeric values in the range from 0 to 99999999.
- The acceptable dateFrom values range from 1970-01-01 to 3000-12-31.
- You cannot use identical dateFrom values for different rates (i.e., one date = one set of rates).
Usage Examples
Adding new cost of work rates for a user
To simplify this operation, follow the below steps:
- Submit the GET/userRates/{uid} request to get the actual data;
- Add the data on the new cost of work rate to the received response;
- Use the changed response in the body of your PUT request and submit it.
GET Response Example
[
{
"dateFrom": "2023-01-04",
"regularRate": 45,
"overtimeRate": 67.5,
"leaveRates": [
{
"leaveTypeId": 2,
"rate": 45
},
{
"leaveTypeId": 3,
"rate": 45
}
]
}
]
PUT Body Example
[
{
"dateFrom": "2023-01-04",
"regularRate": 45,
"overtimeRate": 67.5,
"leaveRates": [
{
"leaveTypeId": 2,
"rate": 45
},
{
"leaveTypeId": 3,
"rate": 45
}
]
},
{
"dateFrom": "2023-04-12",
"regularRate": 50
}
]
PUT Request Example
curl -X PUT "<actiTIME URL>/api/v1/userRates/1" -H "accept: application/json; charset=UTF-8" -H "Content-Type: application/json; charset=UTF-8" -u "username:password" -d "[{ \"dateFrom\": \"2023-01-04\", \"regularRate\": 45, \"overtimeRate\": 67.5, \"leaveRates\": [ { \"leaveTypeId\": 2, \"rate\": 45 }, { \"leaveTypeId\": 3, \"rate\": 45 } ] },{ \"dateFrom\": \"2023-04-12\", \"regularRate\": 50 }]"
PUT Response Example
[
{
"dateFrom": "2023-01-04",
"regularRate": 45,
"overtimeRate": 67.5,
"leaveRates": [
{
"leaveTypeId": 2,
"rate": 45
},
{
"leaveTypeId": 3,
"rate": 45
}
]
},
{
"dateFrom": "2023-04-12",
"regularRate": 50,
"overtimeRate": 75,
"leaveRates": [
{
"leaveTypeId": 2,
"rate": 50
},
{
"leaveTypeId": 3,
"rate": 50
}
]
}
]
Changing a single cost of work rate of a user
To simplify this operation, follow the below steps:
- Submit the GET/userRates/{uid} request to get the actual data;
- Modify parameters for the required cost of work rate in the received response;
- Use the changed response in the body of your PUT request and submit it.
GET Response Example
[
{
"dateFrom": "2023-01-04",
"regularRate": 45,
"overtimeRate": 67.5,
"leaveRates": [
{
"leaveTypeId": 2,
"rate": 45
},
{
"leaveTypeId": 3,
"rate": 45
}
]
}
]
PUT Body Example
[
{
"dateFrom": "2023-01-04",
"regularRate": 45,
"overtimeRate": 67.5,
"leaveRates": [
{
"leaveTypeId": 2,
"rate": 50
},
{
"leaveTypeId": 3,
"rate": 45
}
]
}
]
PUT Request Example
curl -X PUT "<actiTIME URL>/api/v1/userRates/1" -H "accept: application/json; charset=UTF-8" -H "Content-Type: application/json; charset=UTF-8" -u "username:password" -d "[ { \"dateFrom\": \"2023-01-04\", \"regularRate\": 45, \"overtimeRate\": 67.5, \"leaveRates\": [ { \"leaveTypeId\": 2, \"rate\": 50 }, { \"leaveTypeId\": 3, \"rate\": 45 } ] }]"
PUT Response Example
[
{
"dateFrom": "2023-01-04",
"regularRate": 45,
"overtimeRate": 67.5,
"leaveRates": [
{
"leaveTypeId": 2,
"rate": 50
},
{
"leaveTypeId": 3,
"rate": 45
}
]
}
]
Deleting all cost of work rates of a user
To delete all cost of work rates of a user, use an empty array [] as the body of the PUT request.
Please note that THE DELETED DATA CANNOT BE RESTORED.
PUT Request Example
curl -X PUT "<actiTIME URL>/api/v1/userRates/1" -H "accept: application/json; charset=UTF-8" -H "Content-Type: application/json; charset=UTF-8" -u "username:password" -d "[]"
PUT Response Example
[]
Replacing all the existing rates with new ones
To replace all the existing cost of work rates with the new ones, just specify these rates in the PUT request body. All the previously existing rates will be deleted automatically once you submit the request.
PUT Body Example
[
{
"dateFrom": "2023-01-01",
"regularRate": 30
},
{
"dateFrom": "2023-04-01",
"regularRate": 40
}
]
PUT Request Example
curl -X PUT "<actiTIME URL>/api/v1/userRates/1" -H "accept: application/json; charset=UTF-8" -H "Content-Type: application/json; charset=UTF-8" -u "username:password" -d "[ { \"dateFrom\": \"2023-01-01\", \"regularRate\": 30 }, { \"dateFrom\": \"2023-04-01\", \"regularRate\": 40 }]"
PUT Response Example
[
{
"dateFrom": "2023-01-01",
"regularRate": 30,
"overtimeRate": 45,
"leaveRates": [
{
"leaveTypeId": 2,
"rate": 30
},
{
"leaveTypeId": 3,
"rate": 30
}
]
},
{
"dateFrom": "2023-04-01",
"regularRate": 40,
"overtimeRate": 60,
"leaveRates": [
{
"leaveTypeId": 2,
"rate": 40
},
{
"leaveTypeId": 3,
"rate": 40
}
]
}
]
More info on how to use requests for processing users’ cost of work rates is available in Swagger at the following URL:
<your actiTIME URL>/api/v1/swagger
