API

Kickidler API reference

The API allows you to use the functionality of Kickidler employee monitoring software in your personal projects.

The API is written for developers and contains documentation.

Kickidler API operates in accordance with the settings of the Central Server through HTTP, HTTPS.

Note: The Central Server by default uses the HTTP protocol. We recommend that you make all API requests over HTTPS to ensure cyber safety.

Request format

<ProtocolCS>://<hostCS>:<portCS>/api/<API version>/<request>

When working with Kickidler API, each request must contain input element.

<header> Content-Type: application/json
 

Kickidler API returns JSON-encoded responses.

Format description
<ProtocolCSС> HTTP/HTTPS protocol to access Central Server.
<hostCS> domain name of the Central Server in DNS or IP address of the Central Server.
<portCS> port to connect to the Central Server. The default port is 8123.
<API version> API version number. The following API versions are currently implemented in the program:
  • v1.0

Errors

Kickidler uses conventional HTTP response codes to indicate the success or failure of an API request.

If the API resource is correct but the request contains an error, the response status code will include a JSON containing information about the error.

HTTP status code summary
200 - OK Everything worked as expected.
400 - Bad Request The request was unacceptable, often due to missing a required parameter.
403 - Forbidden The API token does not have permissions to perform the request (or it has expired).
404 - Not Found The requested resource does not exist.

Authentication

Kickidler uses API tokens to authenticate requests, and they must be subsequently used to sign each API request.

The token session timeout happens 30 minutes after the last request has been made.

After the token expires, it must be obtained again.

Authorization is required to obtain a token.

Request

auth

Request parameters

Parameter Description
username User login from the Central Server system of records.
password User password from the Central Server system of records.

Example request

curl  127.0.0.1:8123/api/v1.0/auth \
--request GET \
--header "Content-Type: application/json" \
--data '{"username":"API","password":"APIPASSWORD"}'

Example response


{
    "token": "{11b9c22a-219a-44cd-a9e0-a146d24f4d8c}",
    "username": "admin"
}

Requests

Note:! There is an optional id parameter for all requests, which is used to identify the sent request. If you have a large number of requests, when you use the id parameter, the identifier of the sent request will be shown in the response.

List of employees and departments

Method

GET

Request

organization-structure

Request parameters

Parameter Description
id Request identifier. An optional parameter that is included in the response when the id parameter is used in the request.
token Request authentication token.
 

Response parameters

Attribute Data type Description
request_id string Identifier of the request. An optional parameter that is included in the response when the id parameter is used in the request.
structure object structure of the organization
 
“Structure” object
Attribute Data type Description
id string identifier of root department
parent_id string identifier of parent department, root department is assigned null
name string root department name
departments array array of subsidiary departments department
employees array array of employees employee, root department is assigned null
“Department” array
Attribute Data type Description
id string identifier of the department
parent_id string identifier of the parent department
name string department name
departments array array of subsidiary departments department
employees array array of employees employee
“Employee” object
Attribute Data type Description
id string identifier of the employee
department_id string identifier of the department where the employee works
name string employee name
surname string employee surname

Request structure


curl  127.0.0.1:8123/api/v1.0/organization-structure \
--request GET \
--header "Content-Type: application/json" \
--data '{
        "id":" ",
        "token":"{ }"
    }'

Response structure


{
    "request_id" : " ",
    "structure" : {
        "id" : " ",
        "parent_id" : " ",
        "name" : " ",
        "departments" : [
            department
        ]
        "employees" : [
            employee
        ]
}

Example response


{
    "request_id": "1",
    "structure": {
        "departments": [
            {
                "departments": [],
                "employees": [
                    {
                        "department_id": "1",
                        "id": "a37aeb2279fd4a0f8d506075ec93347f",
                        "name": "Jeff",
                        "surname": "Smith"
                    }
                ],
                "id": "1",
                "name": "Default department",
                "parent_id": "0"
            }
        ],
        "employees": [],
        "id": "0",
        "name": "Company",
        "parent_id": ""
    }
}

Data from reports on time/productivity

Method

GET

Request

report-productivity

Request parameters

Parameter Format Description
id string Identifier of the request. An optional parameter that is included in the response when the id parameter is used in the request.
token string request authentication token
period_begin  string in the ISO: "YYYY-MM-DDThh:mm" format start-date parameter in the report request. Must be UTC

cannot be greater than period_end
period_end string in the ISO: "YYYY-MM-DDThh:mm" format end-date parameter in the report request. Must be UTC

should be greater than period_begin and earlier than current time.
worktime_only string parameter that determines if the request includes only the working time. If the value is 1, the response will include only the working time for the specified period. If the value is 0, the response will include total hours.
timezone_offset string in the ISO format:

+-hhmm

 difference between local time and UTC for correct performance of the production calendar.

For example: UTC offset for Boston "-0500"
department_id string

Identifier of the department or employee you want to generate the report for.

You must specify either department_id or employee_id in the request.

In order to generate the report for the entire company, the identifier of the root department should be specified as 0.
employee_id string
 

Response parameters

Attribute Data type Description
request_id object Identifier of the request. An optional parameter that is included in the response when the id parameter is used in the request.
departments array array of department objects
 
“Department” array
Attribute Data type Description
id string identifier of the department
parent_id string identifier of parent department, root department is assigned null
name string department name
productivity object reported data grouped by the company's structure element productivity_data
departments array array of subsidiary departments department
employees array array of employees employee, root department is assigned null
“Productivity_data” object
Attribute Data type Description
total_time integer total amount of activity and idle time in seconds
activity_time integer the amount of activity time in seconds
unproductive_time integer the amount of unproductive activity time in seconds
neutral_time integer the amount of neutral activity time in seconds
productive_time integer the amount of productive activity time in seconds
uncategorized_time integer the amount of uncategorized activity time in seconds
idle_time integer the amount of idle time in seconds
“Employee” object
Attribute Data type Description
id string identifier of employee
department_id string identifier of the department where the employee works
department_name string parent department name
name string employee name
surname string employee surname
productivity array reported data grouped by the employee productivity_data

Request structure


curl --request GET --header "Content-Type: application/json" \
--data '{"id": "", 
        "token": "{ }",
        "period_begin": "YYYY-MM-DDThh:mm", 
        "period_end": "YYYY-MM-DDThh:mm", 
        "timezone_offset": "+-hhmm", 
        "worktime_only": "0", 
        "department_id": "0", 
        "employee_id": "" 
    }' 127.0.0.1:8123/api/v1.0/report-productivity

Response structure


{
    "request_id" : " ",
    "departments" : [
        department,
    ]
}

Example response


{
    "departments": {
        "departments": [
            {
                "departments": [],
                "employees": [
                    {
                        "department_id": "1",
                        "department_name": "Default department",
                        "id": "a37aeb2279fd4a0f8d506075ec93347f",
                        "name": "Jeff",
                        "productivity": {
                            "activity_time": 237,
                            "idle_time": 830,
                            "neutral_time": 0,
                            "productive_time": 196,
                            "total_time": 1067,
                            "uncategorized_time": 41,
                            "unproductive_time": 0
                        },
                        "surname": "Smith"
                    }
                ],
                "id": "1",
                "name": "Default department",
                "parent_id": "0",
                "productivity": {
                    "activity_time": 237,
                    "idle_time": 830,
                    "neutral_time": 0,
                    "productive_time": 196,
                    "total_time": 1067,
                    "uncategorized_time": 41,
                    "unproductive_time": 0
                }
            }
        ],
        "employees": [],
        "id": "0",
        "name": "Company",
        "parent_id": "",
        "productivity": {
            "activity_time": 237,
            "idle_time": 830,
            "neutral_time": 0,
            "productive_time": 196,
            "total_time": 1067,
            "uncategorized_time": 41,
            "unproductive_time": 0
        }
    },
    "request_id": "2"
}

Data from the report on working hours

Method

GET

Request

report-workinghours

Request parameters

Parameter Format Description
id string Identifier of the request. An optional parameter that is included in the response when the id parameter is used in the request
token string Request authentication token
period_begin  string in ISO "YYYY-MM-DDThh:mm" format start-date parameter in the report request. Must be UTC

cannot be greater than period_end
period_end string in ISO "YYYY-MM-DDThh:mm" format end-date parameter in the report request. Must be UTC

should be greater than period_begin and earlier than current time
timezone_offset string in ISO +-hhmm format difference between local time and UTC for correct performance of the production calendar.

For example: UTC offset for Boston "-0500"
department_id string

Identifier of the department or employee you want to generate the report for.

You must specify either department_id or employee_id in the request.

In order to generate the report for the entire company, the identifier of the root department should be specified as 0.
employee_id string
 

Response parameters

Attribute Data type Description
request_id object Identifier of the request. An optional parameter that is included in the response when the id parameter is used in the request
summary_data object reported data grouped by all employees workinghours
employee_rows array array of data on employees rows
 
“workinghours” object
Attribute Data type Description
latenesses integer total time of late arrivals to work in seconds
number_of_latenesses integer total number of late arrivals
undertimes integer total time of leaving work early in seconds
number_of_undertimes integer total number of leaving early
work_time integer total time at work in seconds
absences integer total number of absences
business_trips integer total number of business trips
vacations integer total number of vacations
sick_leaves integer total number of sick leaves
“rows” array
Attribute Data type Description
date string date for which the data is given
id string identifier of employee
department_id string identifier of parent department
department_name string parent department name
name string employee name
surname string employee surname
first_activity string time of the first activity of the employee during the day in the “hh:mm:ss” format
last_activity string time of the last activity of the employee during the day in the “hh:mm:ss” format. for the current day the time of the last activity of the employee is 00:00:00
workinghours object reported data grouped by the employee workinghours

Request structure

curl --request GET --header "Content-Type: application/json" \
--data '{"id": " ", 
    "token": "{ }",
    "period_begin": "YYYY-MM-DDThh:mm", 
    "period_end": "YYYY-MM-DDThh:mm", 
    "timezone_offset": "+-hhmm", 
    "department_id": "0", 
    "employee_id": "" 
}' 127.0.0.1:8123/api/v1.0/report-workinghours

Response structure


{
    "request_id" : " ",
    "summary_data" : {
        workinghours
    }
    "employee_rows" : [
        rows
    ]

}

Example response


{
    "employee_rows": [
        {
            "date": "2022-01-11",
            "department_id": "1",
            "department_name": "Default department",
            "first_activity": "09:09:00",
            "id": "a37aeb2279fd4a0f8d506075ec93347f",
            "last_activity": "18:59:00",
            "name": "Jeff",
            "surname": "Smith",
            "workinghours": {
                "absences": 0,
                "business_trips": 0,
                "latenesses": 540,
                "number_of_latenesses": 1,
                "number_of_undertimes": 0,
                "sick_leaves": 0,
                "undertimes": 0,
                "vacations": 0,
                "work_time": 0
            }
        }
    ],
    "request_id": "2",
    "summary_data": {
        "absences": 0,
        "business_trips": 0,
        "latenesses": 540,
        "number_of_latenesses": 1,
        "number_of_undertimes": 0,
        "sick_leaves": 0,
        "undertimes": 0,
        "vacations": 0,
        "work_time": 0
    }
}