Users Resource

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

GET/users/{uid}
GET/users/me
GET/users
GET/users/{uid}/schedule

User Properties

User properties available via API:

Property Description
id Unique user identifier.
departmentId ID of the department the user belongs to.
timeZoneGroupId ID of the time zone group the user belongs to.
hired User’s hire date.
email User’s email.
fullName User’s full name.
Consists of first name, middle initial (MI) and last name of the user.
username User’s username. Must be unique within the system.
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

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

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 "<actiTIME URL>/api/v1/users/13" 
-H "accept: application/json; charset=UTF-8" 
-H "authorization: Basic YWRtaW46bWFuYWdlcg=="

Example Response:

{
  "id": 13,
  "username": "hr",
  "active": true,
  "firstName": "Jane",
  "middleName": "",
  "lastName": "White",
  "departmentId": 6,
  "timeZoneGroupId": -1,
  "hired": "2018-11-28",
  "email": "demodata@actitime.com",
  "fullName": "Jane White"
}

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

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 "<actiTIME URL>/api/v1/users/me" 
-H "accept: application/json; charset=UTF-8" 
-H "authorization: Basic YWRtaW46bWFuYWdlcg=="

Example Response:

{
  "id": 1,
  "username": "admin",
  "active": true,
  "firstName": "John",
  "middleName": "M",
  "lastName": "Doe",
  "departmentId": 5,
  "timeZoneGroupId": -1,
  "hired": "2018-11-28",
  "email": "demodata@actitime.com",
  "fullName": "John M. Doe"
}

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

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 hired 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 "<actiTIME URL>/api/v1/users?offset=0&limit=2&sort=%2Bhired&includeReferenced=departments" 
-H "accept: application/json; charset=UTF-8" 
-H "authorization: Basic YWRtaW46bWFuYWdlcg=="

Example Response

{
  "offset": 0,
  "limit": 2,
  "items": [
    {
      "id": 1,
      "username": "admin",
      "active": true,
      "firstName": "John",
      "middleName": "M",
      "lastName": "Doe",
      "departmentId": 5,
      "timeZoneGroupId": -1,
      "hired": "2018-11-28",
      "email": "demodata@actitime.com",
      "fullName": "John M. Doe"
    },
    {
      "id": 13,
      "username": "hr",
      "active": true,
      "firstName": "Jane",
      "middleName": "",
      "lastName": "White",
      "departmentId": 6,
      "timeZoneGroupId": -1,
      "hired": "2018-11-28",
      "email": "demodata@actitime.com",
      "fullName": "Jane White"
    }
  ],
  "departments": {
    "5": {
      "id": 5,
      "name": "Top Management",
      "default": false
    },
    "6": {
      "id": 6,
      "name": "HR & Finance",
      "default": false
    }
  }
}

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

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 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 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 "<actiTIME URL>/api/v1/users/1/schedule?dateFrom=2019-01-01&dateTo=2019-01-15" 
-H "accept: application/json; charset=UTF-8" 
-H "authorization: Basic YWRtaW46bWFuYWdlcg=="

Example Response:

{
  "dateFrom": "2019-01-01",
  "dateTo": "2019-01-15",
  "schedule": [
    480,
    480,
    480,
    480,
    0,
    0,
    480,
    480,
    480,
    480,
    480,
    0,
    0,
    480,
    480
  ]
}

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