User API

Updated by Daniel Sjögren

User API

We have opened up parts of our User API for our external partners and customers to be able to integrate with.

We allow for the following data to be available:

  • Shift data
    • Employees upcoming 20 shifts (nothing beyond published date).
    • Unassigned 20 upcoming shifts(nothing beyond published date).
      Info returned:
      • Employee name
      • Date and from and to time
      • Unit name and Shift type name
      • Break(s) from and to time.
      • Total break duration in minutes 
      • Section name
      • Shift Id (hashed for security reasons)
  • Leave applications
    • All historic leave app
    • All upcoming leave app
      Info returned:
      • Leave reason name
      • Employee name
      • From date & time - to date and time.
      • Date & time when the leave applications was sent
      • Status of the leave application (denied, pending or approved)
      • Employee’s comment in leave application
      • All-day True or False, the flag shows whether the leave application has been created for part of the day or the whole day
      • Leave application Id (hashed for security reasons)
    • Leave managers: get list of all managers that could be selected as employee’s leave application receivers.
    • Leave-reasons this endpoint will return a list of all leave reasons that could be selected when creating a leave application.
    • Create leave applications: it is also possible to create leave applications through the user API with the endpoint POST /users/leave-applications

Technical description

The user API will be exposed on following URLs: user-api-rc.quinyx.com and user-api.quinyx.com each reflecting RC and production environment.

These are base URLS. They do not return any content (i.e they return 404 error). However, you can use them to build the full URL for corresponding endpoint(s)for example: for GET /users/shifts the full url is https://user-api-rc.quinyx.com/v2/users/shifts

The current API version is v2, so all routes will have a v2 prefix in front of them. Swagger documentation is available and can be accessed here:

Please use our existing Swagger documentation above to get all URLs.
The current endpoints we have in the user API:
POST /oauth/token

This endpoints is used to get access token (which is used to access other endpoints that are secured) and refresh token (which is used to generate new access tokens). Default life time for the access token is 15 minutes, and for the refresh token is 30 days.

To get tokens using employee login credentials grantType needs to be set to password and sent together with the username and password. Content-Type header should be set to application/json and request body can look like this:

{"grantType": "password","username": "empployeeEmailInTheQuinyxApp","password": "empployeePasswordInTheQuinyxApp"}

To get new tokens using existing refresh token grantType needs to be set to refresh_token and sent together with the refreshToken. Refresh token can be used only once so it must be replaced by newly received refresh token. Content-Type header should be set to application/json and request body can look like this:

{"grantType": "refresh_token","refreshToken": "receivedRefreshToken"}

Received access token obtained above should be passed with each call - this should be done in the form of request header, such as: header 'Authorization: Bearer <token>'.

GET /users/shifts

This endpoint will return employees upcoming or unassigned shifts. The number of shifts in the response is limited to 20 shifts, and search will be performed only in published period, up to 90 days in the future. To show upcoming shifts filter parameter in query string should be set to upcoming (?filter=upcoming), and to show unassigned shifts filter parameter in query string should be set to unassigned (?filter=unassigned).

GET /users/leave-applications

This endpoint will return all upcoming leave applications, starting from today, or historical applications, ending today or earlier. To show upcoming leave applications filter parameter in query string should be set to upcoming (?filter=upcoming), and to show historical leave applications filter parameter in query string should be set to historical (?filter=historical).

GET /users/leave-reasons

This endpoint will return a list of all leave reasons that could be selected when creating a leave application. Leave reason id property from any of the items in the leaveReasons list from the response should be used when creating a request to create leave application.

GET /users/leave-applications/managers

This endpoint will return a list of all managers that could be selected as employee’s leave application receivers. defaultManager property from any of the items in the leaveManagers list from the response shows whether that manager should be selected as the default manager in the list while id property should be used when creating a request to create leave application.

POST /users/leave-applications

This endpoint is used to create leave applications. Content-Type header should be set to application/json and request body can look like this:

1 2 3 4 5 6 7 8 { "from": "2020-12-24 00:00:00", "to": "2020-12-24 00:00:00", "leaveReasonId": "kBep_ZtJ1sce0EXuI_9Evt.4qUR7INSe06UTygqpqLxc", "leaveManagerId": "hd58ElPA.IW0FHctO8oCRAhGTetM2yCxIs.63wgYdfB75C0--", "comment": "Employee comment to the leave application", "allDay": false }

From, to and leaveReasonId fields are mandatory, the other fields can be left out from the request.

From and to date times should be sent in the format Y-m-d H:i:s, to date time can’t be set before from. If employee selects leave that should last for one whole calendar day (same date in the calendar picker) then both from and to time should be set to the same value, like in the example 2020-12-24 00:00:00 which means that this leave will last 24 hours starting on the midnight of the given day and ending on the same day in 23:59:59. If leave lasts more than one calendar day then last date user has selected in the calendar should be sent in the request with 00:00:00 and the system will automatically handle end time.

When the allDay flag has been activated then user must manually select times on both from and to dates. this flag doesn’t need to be sent along with the request because its really needed and its not used by the backend logic, should be used by frontend application only, if time in from and to parameters is 00:00:00 or leave lasts longer than 24 hours then its automatically allDay true by default, otherwise its false.

leaveReasonId is the id from the selected option from the GET /users/leave-reasons response. This option must be selected by the employee.

leaveManagerId is the id from the selected option from the GET /users/leave-applications/managers response. It is not required and if not sent in the request system automatically find the manager who should receive the leave application. Leave manager that should be automatically selected in the list has defaultManager flag set to true.

Comment is a optional field where employee can leave a comment related to the created leave and it has not any specific character length limit.

If successful, response will be returned with HTTP code 201 and the leave application object under the leaveApp property in the same format as under the GET /users/leave-applications endpoint.

If we have some validation messages that are preventing the employee from creating the leave the why will be returned under the HTTP code 400 or 403 in the format:

1 2 3 4 5 6 { "err": { "code": 400, "msg": "Error message" } }

msg field in the response can be one of the following and it closely describes what was the problem with creating the leave:

INVALID_LEAVE_REASON, OVERLAPPING_LEAVES, INVALID_LEAVE_MANAGER, INVALID_ID: hashedInvalidId, LEAVEAPP_MAX_CONSECUTIVE_DAYS, LEAVEAPP_MAX_OCCASIONS, LEAVEAPP_MAX_DAYS_IN_PERIOD, LEAVEAPP_MIN_DAYS_BETWEEN, LEAVEAPP_APPROVED_PUNCH_IN_PERIOD, LEAVEAPP_LOCKED_SALARIES_IN_PERIOD, LEAVEAPP_PRECEEDING_LEAVE_WITHOUT_WORK, CANT_EDIT_LEAVE_APP, NO_VALID_RECEIVER_FOUND, NOT_VALID_TIME_TRACKER_BALANCE.

How Did We Do?