Users Resource

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

GET/users
GET/users/me
GET/users/{uid}
GET/users/{uid}/schedule
PATCH/users/{uid}
POST/users
POST/users/invitation

User Properties

User properties available via API:

Property Description
id Unique user identifier.
departmentId ID of the department a user belongs to.
timeZoneGroupId ID of the time zone group a user belongs to.
hired User’s hire date (from 1970-01-01 to 3000-12-31).
releaseDate User’s release date (from 1970-01-01 to 3000-12-31).
email User’s email.
fullName User’s full name.
Consists of first name, middle initial (MI) and last name of a user.
username User’s username. Must be unique within the system.
password User’s password for accessing the product.
An admin can modify this property but no one can retrieve it.
active Status of user’s account. Possible values: true (active), false (disabled).
firstName User’s first name.
middleName User’s middle initial.
lastName User’s last name.

Required Permissions

The following user’s properties can be retrieved by any user of the system:

  • id
  • departmentId
  • timeZoneGroupId
  • active
  • fullName
  • firstName
  • middleName
  • lastName

The following user’s properties can be retrieved only by users with the ‘Manage Accounts & Permissions’ permission (all users’ properties are available):

  • username
  • email
  • hired
  • releaseDate

The required permissions for retrieving users’ schedules are described in the ‘Retrieve User Schedule’ section.

The ‘password’ property can only be modified by users with the ‘Manage Accounts & Permissions’ permission. It cannot be retrieved by anyone (even by users with the ‘Manage Accounts & Permissions’ permission).

Retrieve List of Users

Use the following request to retrieve a list of users with their properties:

GET/users

The request can be specified with several parameters:

Parameter Description
offset Pagination offset.
If provided, first n users will be not shown in the list.
limit Pagination limit.
If provided, the number of returned users will be limited to n.
email If provided, only users with given email will be returned (only one email should be provided).
ids If provided, only users with given IDs will be returned.
department If provided, only users from given departments will be returned.
timeZoneGroup If provided, only users from given time zone groups will be returned.
active If provided, only users with enabled or disavled access to actiTIME will be returned.
If not provided, users with enabled and disabled access to actiTIME will be returned.
username If provided, only user with exact username match will be returned (only one username should be provided).
name If provided, only users with full name (first name + MI + last name) containing all of given words will be returned.
sort Sets sorting of the results.
Users can be sorted by last name, hire date, username, department or time zone group.
If the results in the response are requested to be sorted by unavailable properties, the users whose properties (hired date, username) are not available will be excluded from the response.
includeReferenced Additional data that can also be included in the response:
– departments’ properties;
– time zone groups’ properties.

Also see the ‘Required Permissions’ section.

Example Request:

curl -X GET "&ltactiTIME URL&gt/api/v1/users?offset=0&limit=2&sort=%2BlastName&includeReferenced=departments" -H "accept: application/json; charset=UTF-8" -u "username:password"

Example Response

{
  "offset": 0,
  "limit": 2,
  "items": [
    {
      "id": 16,
      "username": "pm",
      "active": true,
      "firstName": "Daniel",
      "middleName": "",
      "lastName": "Alvarez",
      "departmentId": 7,
      "timeZoneGroupId": 3,
      "hired": "2021-03-10",
      "releaseDate": null,
      "email": "demodata@actitime.com",
      "allowedActions": {
        "canSubmitTimetrack": true
      },
      "fullName": "Daniel Alvarez"
    },
    {
      "id": 22,
      "username": "sales",
      "active": true,
      "firstName": "Hannah",
      "middleName": "",
      "lastName": "Klein",
      "departmentId": 5,
      "timeZoneGroupId": 3,
      "hired": "2021-03-10",
      "releaseDate": null,
      "email": "demodata@actitime.com",
      "allowedActions": {
        "canSubmitTimetrack": true
      },
      "fullName": "Hannah Klein"
    }
  ],
  "departments": {
    "5": {
      "id": 5,
      "name": "Top Management",
      "default": false
    },
    "7": {
      "id": 7,
      "name": "Production",
      "default": false
    }
  }
}

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

Retrieve Properties of the Authorized User

Use the following request to retrieve properties of the authorized user:

GET/users/me

Example Request:

curl -X GET "&ltactiTIME URL&gt/api/v1/users/me" -H "accept: application/json; charset=UTF-8" -u "username:password"

Example Response:

{
  "id": 1,
  "username": "admin",
  "active": true,
  "firstName": "John",
  "middleName": "M",
  "lastName": "Doe",
  "departmentId": 5,
  "timeZoneGroupId": -1,
  "hired": "2021-03-10",
  "releaseDate": null,
  "email": "demodata@actitime.com",
  "allowedActions": {
    "canSubmitTimetrack": true
  },
  "fullName": "John M. Doe"
}

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

Retrieve User Properties

Use the following request to retrieve properties of the user with given ID:

GET/users/{uid}

Also see the ‘Required Permissions’ section.

Example Request:

curl -X GET "&ltactiTIME URL&gt/api/v1/users/13" -H "accept: application/json; charset=UTF-8" -u "username:password"

Example Response:

{
  "id": 13,
  "username": "hr",
  "active": true,
  "firstName": "Jane",
  "middleName": "",
  "lastName": "White",
  "departmentId": 6,
  "timeZoneGroupId": -1,
  "hired": "2021-03-10",
  "releaseDate": null,
  "email": "demodata@actitime.com",
  "allowedActions": {
    "canSubmitTimetrack": true
  },
  "fullName": "Jane White"
}

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

Retrieve User Schedule

Use the following request to retrieve schedule (in minutes by days) of the user with given ID:

GET/users/{uid}/schedule

The request can be specified with several parameters:

Parameter Description
uid User ID.
dateFrom Start date of the requested schedule, inclusive.
If not provided, then the same day of the previous month is used.
dateTo End date of the requested schedule, inclusive.
If not provided, then today date is used OR the same day of the next month if dateFrom >= today.

Required Permissions

User schedules that can be retrieved are defined by the authorized user’s permissions. Also note that any user (even with no permissions at all) can access their own schedule.

Permission Available Users
Manage Accounts & Permissions All Users
Manage PTO & Sick Days Settings All Users
Modify & Approve Users’ Time-Track Assigned Team
Manage Cost & Billing Data Assigned Team

Example Request:

curl -X GET "&ltactiTIME URL&gt/api/v1/users/1/schedule?dateFrom=2021-06-01&dateTo=2021-06-14" -H "accept: application/json; charset=UTF-8" -u "username:password"

Example Response:

{
  "dateFrom": "2021-06-01",
  "dateTo": "2021-06-14",
  "schedule": [
    480,
    480,
    480,
    480,
    0,
    0,
    480,
    480,
    480,
    480,
    480,
    0,
    0,
    480
  ]
}

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

Update User Properties

Use the following request to update the properties of the user account with given ID:

PATCH/users/{uid}

Only the following properties can be updated: ‘firstName’, ‘lastName’, ‘middleName’, ‘username’, ‘password’, ‘email’, ‘active’, ‘hired’, ‘releaseDate, ‘departmentId’, and ‘timeZoneGroupId’.

Please note:

  • new ‘password’ property (user password) must comply with the product password policy;
  • the authorized user cannot modify their own ‘active’ property (account status);
  • the authorized user cannot set their own ‘hired’ property (hire date) to the future;
  • the ‘hired’ property (hire date) of the last active License Manager cannot be set to the future via API;
  • the ‘hired’ property (hire date) of any user cannot be set to the later date via API if this change is to lead to deleting of the user’s time-track;
  • the ‘active’ property (account status) of the last active License Manager cannot be set to ‘false’ (inactive) via API.

Required Permissions

To be able to modify a user account, the user should have the ‘Manage Accounts & Permissions’ permission.

Example Request:

curl -X PATCH "&ltactiTIME URL&gt/api/v1/users/13" -H "accept: application/json; charset=UTF-8" -H "Content-Type: application/json; charset=UTF-8" -u "username:password" -d "{ \"departmentId\": 7, \"timeZoneGroupId\": -1, \"firstName\": \"Helena\", \"lastName\": \"Smith\"}"

Example Response:

{
  "id": 13,
  "username": "hr",
  "active": true,
  "firstName": "Helena",
  "middleName": "",
  "lastName": "Smith",
  "departmentId": 7,
  "timeZoneGroupId": -1,
  "hired": "2021-03-10",
  "releaseDate": null,
  "email": "demodata@actitime.com",
  "allowedActions": {
    "canSubmitTimetrack": true
  },
  "fullName": "Helena Smith"
}

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

Create User Account

Use the following request to create a new user account:

POST/users

While creating a user account,

  • the following properties are mandatory: ‘firstName’, ‘lastName’, ‘email’, ‘username’, ‘password’;
  • the following properties are optional: ‘middleName’, ‘active’, ‘hired’, ‘releaseDate, ‘departmentId’, ‘timeZoneGroupId’.

Required Permissions

To be able to create a new user account a user should have the ‘Manage Accounts & Permissions’ permission.

Please note:

  • a new user account is created with the default permissions template;
  • if the maximum of allowed active user accounts is reached, no new user accounts can be created via API;
  • if there is an integration with actiPLANS, a new user account is created with disabled access to actiPLANS.

Example Request:

curl -X POST "&ltactiTIME URL&gt/api/v1/users" -H "accept: application/json; charset=UTF-8" -H "Content-Type: application/json; charset=UTF-8" -u "username:password" -d "{ \"email\": \"demodata@actitime.com\", \"password\": \"123456\", \"username\": \"project_manager\", \"firstName\": \"John\", \"lastName\": \"Snow\"}"

Example Response:

{
  "id": 26,
  "username": "project_manager",
  "active": true,
  "firstName": "John",
  "middleName": "",
  "lastName": "Snow",
  "departmentId": -1,
  "timeZoneGroupId": -1,
  "hired": "2021-06-15",
  "releaseDate": null,
  "email": "demodata@actitime.com",
  "allowedActions": {
    "canSubmitTimetrack": true
  },
  "fullName": "John Snow"
}

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

Invite User

Use the following request to invite a new user to the system:

POST/users/invitation

While inviting a user,

  • the following properties are mandatory: ‘firstName’, ‘lastName’, ‘email’;
  • the following properties are optional: ‘middleName’, ‘active’, ‘hired’, ‘releaseDate, ‘departmentId’, ‘timeZoneGroupId’;
  • the following properties cannot be specified: ‘username’, ‘password’.
    The ‘username’ value will be generated automatically and the ‘password’ value should be specified by the user who gets the invitation letter.

Required Permissions

To be able to invite a new user an authorized user should have the ‘Manage Accounts & Permissions’ permission.

Please note:

  • a new user account is created with the default permissions template;
  • if the maximum of allowed active user accounts is reached, no new user accounts can be created via API;
  • if there is an integration with actiPLANS, a new user account is created with disabled access to actiPLANS;
  • invitations can be sent if you are using actiTIME Online version (invitations are not available in the actiTIME Self-Hosted versions).

Example Request:

curl -X POST "&ltactiTIME URL&gt/api/v1/users/invitation" -H "accept: application/json; charset=UTF-8" -u "username:password" -H "Content-Type: application/json; charset=UTF-8" -d "{ \"email\": \"jack@actitime.com\", \"firstName\": \"Jack\", \"lastName\": \"Jones\"}"

Example Response:

{
  "id": 25,
  "username": "jack",
  "active": true,
  "firstName": "Jack",
  "middleName": "",
  "lastName": "Jones",
  "departmentId": -1,
  "timeZoneGroupId": -1,
  "hired": "2021-06-15",
  "releaseDate": null,
  "email": "jack@actitime.com",
  "allowedActions": {
    "canSubmitTimetrack": true
  },
  "fullName": "Jack Jones"
}

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