NAV
JSON TypeScript

Roles

Add user role

PUT /company/:company-id:/users/:user-id:/roles/:role:

Example success response:

{
  "status": "success",
  "result": "User role set."
}

class Result {
  status: string;
  result: string;
}

POST Parameters

Required parameter :role:

Title Role Description
Administrator admin Gives the user full access. Users with this level of access can do all.
Read only administrator admin:read Gives the user read access to all sections .Users with this level of access can only view data, they're not allowed to edit or create records.
Read only company admin company:read Gives the user read access to company related data only. For example company details, departments etc.
Company admin company:admin Gives the user full access to company related data only. For example company details, departments etc.
Read only users admin users:read Gives the user read access to company users data only.
Users admin users:admin Gives the user full access to company users data only.For example create, edit or invite users to the company as well as viewing their details.
Read only leave management admin leave-management:read Gives the user read access to leave management settings.
Leave management admin leave-management:admin Gives the user full access to leave management settings.

The user have to be administrator and log in to be able to give roles.

Get user role

GET /company/:company-id:/users/:user-id:/roles

Example success response:

{
  "status": "success",
  "result": [
    "admin",
    "company:read"
  ]
}

class Result {
  status: string;
  result: string;
}

Description

The user have to be administrator or account owner to get roles.

Get all roles

GET /company/:company-id:/users/roles

Example success response:

{
  "status": "success",
  "result": [
    {
      "title": "Administrator",
      "description": "Gives the user full access. Users with this level of access can do all.",
      "value": "admin"
    },
    {
      "title": "Read only administrator",
      "description": "Gives the user read access to all sections .Users with this level of access can only view data, they're not allowed to edit or create records.",
      "value": "admin:read"
    },
    {
      "title": "Read only company admin",
      "description": "Gives the user read access to company related data only. For example company details, departments etc.",
      "value": "company:read"
    },
    {
      "title": "Company admin",
      "description": "Gives the user full access to company related data only. For example company details, departments etc.",
      "value": "company:admin"
    },
    {
      "title": "Read only users admin",
      "description": "Gives the user read access to company users data only.",
      "value": "users:read"
    },
    {
      "title": "Users admin",
      "description": "Gives the user full access to company users data only.For example create, edit or invite users to the company as well as viewing their details.",
      "value": "users:admin"
    },
    {
      "title": "Read only leave management admin",
      "description": "Gives the user read access to leave management settings.",
      "value": "leave-management:read"
    },
    {
      "title": "Leave management admin",
      "description": "Gives the user full access to leave management settings.",
      "value": "leave-management:admin"
    }
  ]
}

class Result {
  status: string;
  result: Roles[];
}

Description

The user have to be administrator to see all roles.

Delete user role

DELETE /company/:company-id:/users/:user-id:/roles/:role:

Example success response:

{
  "status": "success",
  "result": "User role removed."
}

class Result {
  status: string;
  result: string;
}

Description

The user have to be administrator to be able to remove roles.

Company

Create company

POST /company

Request body

{
  "firstName": "John",
  "lastName": "Doe",
  "email": "[email protected]",
  "companyName": "Test company name",
  "password": "user_password",
  "countryId": 1
}

class Request {
  firstName: string;
  lastName: string;
  email: string;
  companyName: string;
  password: string;
  countryId: number;
}

Example success response:

{
  "status": "success",
  "result": "Company created successfully"
}

class Response {
  status: string;
  result: string;
}

Required fields

Field Type Validation Comment
firstName string 1 - 60 characters admin user first name
lastName string 1 - 60 characters admin user last name
email string <= 128 caharcters admin user email
companyName string 1 - 100 characters Legal company name value
password string 10 - 100 characters raw password as it was enetered by user
countryId int 1 - 300 country id from Country list endpoint
token string N/A The value stored in token cookie

This endpoint will create company and admin user at the same time. It is important to note that if user with this email already exists in the system it will automatically be assigned an admin role, in such case the password provided in the registration payload is going to be ignored and the user should use their existing password to login and see and manage their newly created company.

Get company details

Provides full company details

GET /company/:company-id:

Example success response:

{
  "status": "success",
  "result": {
    "company": {
      "id": "com_b762fd848fba96bed5e4dd445adb98",
      "name": "Hippoland ltd.",
      "email": "[email protected]",
      "taxId": "1234567",
      "vatId": "IE1232313",
      "website": "www.example.com",
      "phone": "01 654654",
      "addressLine1": "Updown road",
      "addressLine2": "Nowhere",
      "countryName": "Ireland",
      "state": "Dublin",
      "city": "Dublin",
      "postCode": "D2",
      "createdDate": "2022-04-14T10:05:05.000000Z",
      "createdBy": "HR Omni Administrator",
      "updatedDate": "2022-04-14T10:17:02.000000Z",
      "updatedBy": "HR Omni Administrator"
    }
  }
}

class Company {
  id: string;
  email: string;
  taxId?: string;
  vatId?: string;
  website?: string;
  phone?: string;
  addressLine1?: string;
  addressLine2?: string;
  countryName?: string;
  state?: string;
  city?: string;
  postCode?: string;
  createdDate: string;
  createdBy: string;
  updatedDate?: string;
  updatedBy?: string;
}

Company JSON response fields

Field Type Optional
id uuid NO
name string NO
email string NO
taxId string YES
vatId string YES
website string YES
phone string YES
addressLine1 string YES
addressLine2 string YES
countryName string YES
state string YES
city string YES
postCode string YES
createdDate date NO
createdBy string NO
updatedDate date YES
updatedBy string YES

Other information

This endpoint shows the company details and requires user login and authorisation to access this info.

Update company details

Updates company details. Requires user login + CSRF token + user authorisation

PUT /company/:company-id:

Request body:

{
  "email": "[email protected]",
  "taxId": "1234567",
  "vatId": "IE1232313",
  "website": "www.example.com",
  "phone": "01 654654",
  "addressLine1": "Updown road",
  "addressLine2": "Nowhere",
  "state": "Dublin",
  "city": "Dublin",
  "postCode": "D2"
}

class Request {
  email: string;
  taxId?: string;
  vatId?: string;
  website?: string;
  phone?: string;
  addressLine1?: string;
  addressLine2?: string;
  state?: string;
  city?: string;
  postCode?: string;
}

JSON fields

Field Type Validation Required
email string Valid email address YES
taxId string 1 - 60 characters NO
vatId string 1 - 60 characters NO
website string min 1 character and valid hostname NO
phone string max 20 characters long, valid phone format NO
addressLine1 string 1 - 180 characters NO
addressLine2 string 1 - 180 characters NO
state string 1 - 150 characters NO
city string 1 - 150 characters NO
postCode string 1 - 15 characters NO

No additional fields will be allowed in.

Company user

Create user

POST /company/:companyId:/users

Request body

{
  "firstName": "Jane",
  "lastName": "Doe",
  "email": "[email protected]",
  "phone": "01234567898",
  "addressLine1": "address1",
  "addressLine2": "address2",
  "city": "Dublin",
  "state": "ST",
  "postCode": "01Dub",
  "country": "Ireland",
  "dateOfBirth": "1973-06-12",
  "nationality": "Irish",
  "sendInvite": true
}

class Request {
  firstName: string;
  lastName: string;
  email: string;
  phone?: string;
  addressLine1?: string;
  addressLine2?: string;
  city?: string;
  state?: string;
  postCode?: string;
  country?: string;
  dateOfBirth?: string;
  sendInvite: boolean;
}

Example success response:

{
  "status": "success",
  "result": {
    "user": {
      "id": "***************"
    }
  }
}

class Response {
  status: string;
  result: User;
}

class User {
  id: string;
}

JSON fields

Field Type Validation Required Comment
firstName string 1 - 60 characters YES admin user first name
lastName string 1 - 60 characters YES admin user last name
email string <= 128 caharcters YES admin user email
phone string 20 characters NO maching regex ^[+]{0,1}[\s]{0,1}[(]{0,1}[0-9]{1,4}[)]{0,1}[-\.\s.0-9]*$
addressLine1 string 1 - 100 characters NO User address line 1
addressLine2 string 1 - 100 characters NO User address line 2
city string 1 - 100 characters NO User city
state string 1 - 100 characters NO User state or county
postCode string 1 - 10 characters NO User post code
country string 1 - 30 characters NO user country
dateOfBirth string date NO Date of birth in ISO 8601 format Example: 1973-06-12
nationality string 1 - 30 characters NO Nationality example "Ireland"
sendInvite boolean true/false YES Indicates if user invite email should be send to the user or not.

Update user name

POST /user/edit-name

Request body

{
  "firstName": "Jon",
  "lastName": "Do"
}

class Request {
  firstName: string;
  lastName: string;
}

Example success response:

{
  "status": "success",
  "result": "Details updated successfully."
}

class Response {
  status: string;
  result: string;
}

JSON fields

Field Type Validation Required Comment
firstName string 1 - 60 characters YES user first name
lastName string 1 - 60 characters YES user last name

Information This endpoint will update currently logged-in users first and last name agains their login details. If you want to update the details for a specific company you should use /company/:companyId:/users/:userId: endpoint instead

Update user details

PUT /company/:companyId:/users/:userId:

Request body

{
  "firstName": "Jane",
  "lastName": "Doe",
  "email": "[email protected]",
  "phone": "01234567898",
  "addressLine1": "address1",
  "addressLine2": "address2",
  "city": "Dublin",
  "state": "ST",
  "postCode": "01Dub",
  "country": "Ireland",
  "dateOfBirth": "1900-01-01",
  "nationality": "Irish"
}

class Request {
  firstName: string;
  lastName: string;
  email: string;
  phone?: string;
  addressLine1?: string;
  addressLine2?: string;
  city?: string;
  state?: string;
  postCode?: string;
  country?: string;
  dateOfBirth?: string;
  nationality?: string;
}

Example success response:

{
  "status": "success",
  "result": "User created"
}

class Response {
  status: string;
  result: string;
}

JSON fields

Field Type Validation Required Comment
firstName string 1 - 60 characters YES admin user first name
lastName string 1 - 60 characters YES admin user last name
email string <= 128 caharcters YES admin user email
phone string 20 characters NO maching regex ^[+]{0,1}[\s]{0,1}[(]{0,1}[0-9]{1,4}[)]{0,1}[-\.\s.0-9]*$
addressLine1 string 1 - 100 characters NO User address line 1
addressLine2 string 1 - 100 characters NO User address line 2
city string 1 - 100 characters NO User city
state string 1 - 100 characters NO User state or county
postCode string 1 - 10 characters NO User post code
country string 1 - 30 characters NO user country
dateOfBirth string date NO Date of birth in format 'dd-mm-yyyy'
nationality string 1 - 30 characters NO Nationality example "Ireland"

Set user emergency contact

PUT /company/:companyId:/users/:userId:/emergency-contact

Request body

{
  "name": "aaaaa",
  "email": "[email protected]",
  "phone": "01234567890",
  "relation": "FRIEND",
  "address": "full address 1"
}

class Request {
  name: string;
  email?: string;
  phone: string;
  relation?: string;
  address?: string;
}

enum Relation {
  SPAUSE, PARTNER, PARENT, CHILD, FRIEND, NEIGHBOUR, OTHER
}

Example success response:

{
  "status": "success",
  "result": "Emergency contact set"
}

class Response {
  status: string;
  result: string;
}

JSON fields

Field Type Validation Required Comment
name string 1 - 100 characters YES emergency contact name
email string 1 - 128 characters NO emergency contact email
phone string 1 - 20 characters YES maching regex ^[+]{0,1}[\s]{0,1}[(]{0,1}[0-9]{1,4}[)]{0,1}[-\.\s.0-9]*$
relation enum SPAUSE, PARTNER, PARENT, CHILD, FRIEND, NEIGHBOUR, OTHER NO should be one of the enum cases
address string 1 - 100 characters NO emergency contact name

Other validations

Get employees

GET /company/:company-id:/users/employees?status=ACTIVE,TERMINATED&page=1&pageSize=20&search=John

Example success response:

{
  "status": "success",
  "result": {
    "status": "ACTIVE,TERMINATED",
    "totalRecords": 1,
    "totalPages": 1,
    "currentPage": 0,
    "currentPageSize": 20,
    "result": [
      {
        "userId": "usr_55c167772cede801ca1d83ec8a8e1c",
        "firstName": "john",
        "lastName": "Doe",
        "email": "[email protected]",
        "status": "ACTIVE",
        "createdBy": "john Doe",
        "updatedBy": "john Doe",
        "createdAt": "2022-11-17T14:23:40.000000Z"
      }
    ]
  }
}

class Result {
  status?: statusType;
  search?: string;
  totalRecords: number;
  totalPages: number;
  currentPage: number;
  currentPageSize: number;
  result: User[];
}

class User {
  userId: string;
  firstName: string;
  lastName: string;
  email: string;
  status: string;
  createdBy: string;
  updatedBy: string;
  createdAt: string;
  updatedAt?: string;
}

enum statusType {
  ACTIVE = "ACTIVE",
  IN_TERMINATION = "IN_TERMINATION",
  TERMINATED = "TERMINATED",
}

GET Parameters

parameter name type optional description
status string true You can add one ore more statuses ACTIVE,TERMINATED,IN_TERMINATION
page int true this indicates the page number you request
pageSize int true the maximum records to be included in the page (default page size is 20)
search string true search keywords separated by space. By default matches each exact keyword. In case a more loose search is required simply add * at the end of the keyword. For example black* will match black and blackwater where black will match only black

Lists all employees for the company. The endpoint is protected behind login and requires the appropriate user authorisation/access level.

Get users

GET /company/:company-id:/users?page=1&pageSize=20&search=John

Example success response:

{
  "status": "success",
  "result": {
    "search": "John",
    "totalRecords": 1,
    "totalPages": 1,
    "currentPage": 0,
    "currentPageSize": 20,
    "result": [
      {
        "id": "usr_b762fd848fba96bed5e4dd445adb98",
        "firstName": "John",
        "lastName": "Doe",
        "email": "[email protected]",
        "createdBy": "John Doe",
        "updatedBy": "John Doe",
        "createdAt": "2022-03-28T17:00:00.000000Z",
        "updatedAt": "2022-03-28T17:00:00.000000Z"
      }
    ]
  }
}

class Result {
  search?: string;
  totalRecords: number;
  totalPages: number;
  currentPage: number;
  currentPageSize: number;
  result: User[];
}

class User {
  id: string;
  firstName: string;
  lastName: string;
  email: string;
  createdBy: string;
  updatedBy: string;
  createdAt: string;
  updatedAt?: string;
}

GET Parameters

parameter name type optional description
page int true this indicates the page number you request
pageSize int true the maximum records to be included in the page (default page size is 20)
search string true search keywords separated by space. By default matches each exact keyword. In case a more loose search is required simply add * at the end of the keyword. For example black* will match black and blackwater where black will match only black

Lists all users for the company. The endpoint is protected behind login and requires the appropriate user authorisation/access level.

Get user details

GET /company/:companyId:/users/:userId:

Example response

{
  "status": "success",
  "result": {
    "id": "*******",
    "userInfo": {
      "firstName": "Johny",
      "lastName": "Doe",
      "phone": "+ (353) 83-132-4567",
      "email": "[email protected]",
      "addressLine1": "1 Upper View",
      "addressLine2": "Updown road",
      "city": "Ballsbridge",
      "state": "Dublin",
      "postCode": "01D12345",
      "country": "Ireland",
      "dateOfBirth": "1973-06-12",
      "nationality": "Ireland"
    },
    "emergencyContact": {
      "name": "Jane Doe",
      "phone": "+ (353) 83 153 8740",
      "email": "[email protected]",
      "relation": "SPAUSE",
      "address": "1 Updown road, Dublin, Ireland"
    },
    "createdAt": "2022-03-20T16:07:07.000000Z",
    "createdBy": "John Doe",
    "updatedAt": "2022-03-28T17:00:00.000000Z",
    "updatedBy": "Jim Doe"
  }
}

class Result {
  id: string;
  userInfo: UserInfo;
  emergencyContact?: EmergencyContact;
  createdAt: string;
  createdBy: string;
  updatedAt?: string;
  updatedBy?: string;
}

class UserInfo {
  firstName: string;
  lastName: string;
  email: string;
  phone?: string;
  addressLine1?: string;
  addressLine2?: string;
  city?: string;
  state?: string;
  postCode?: string;
  country?: string;
  dateOfBirth?: string;
  nationality?: string;
}

class EmergencyContact {
  name: string;
  email?: string;
  phone: string;
  relation?: Relation;
  address?: string;
}

This endpoint is protected by login. The logged-in user must have the appropriate authorisation to access the company and its user details with read permissions.

JSON response types table

Field Type Validation Optional Comment
status enum success, error NO indicates if request was successful or not
result mixed N/A NO contains the response object or the error
result.firstName string N/A NO User first name
result.lastName string N/A NO User last name
result.contactDetails object N/A YES User contact details object
result.contactDetails.phone string N/A YES User phone number
result.contactDetails.email string N/A YES User email address
result.contactDetails.addressLine1 string N/A YES User address line 1
result.contactDetails.addressLine2 string N/A YES User address line 2
result.contactDetails.city string N/A YES User city
result.contactDetails.state string N/A YES User state or province
result.contactDetails.postCode string N/A YES User post code
result.contactDetails.country string N/A YES User country
result.contactDetails.dateOfBirth string N/A YES User date of birth
result.contactDetails.nationality string N/A YES User nationality
result.emergencyContact object N/A YES User emergency contact object
result.emergencyContact.name string N/A NO User emergency contact full name
result.emergencyContact.phone string N/A NO User emergency contact phone number
result.emergencyContact.email string N/A YES User emergency contact email address
result.emergencyContact.relation enum SPAUSE, PARTNER, PARENT, CHILD, FRIEND, NEIGHBOUR, OTHER YES Emergency contact relation to the user
result.emergencyContact.address string N/A YES User emergency contact full address
result.createdAt date ISO_8601 NO Date the user record was created
result.createdBy string N/A NO The user who created the record
result.updatedAt date ISO_8601 YES Date the user record was last updated
result.updatedBy string N/A YES The user who last updated the record

Delete user

DELETE /company/:companyId:/users/:userId:

Example success response:

{
  "status": "success",
  "result": "User deleted"
}

class Responce {
  status: string;
  result: string;
}

Department

Create Department

POST /company/:company-id:/departments

Request body

{
  "name": "Department Name",
  "hoursMonday": "0900:1200^1300:1700",
  "hoursTuesday": "0930:1230^1330:1730",
  "hoursWednesday": "0900:1200^1300:1700",
  "hoursThursday": "1400:1700^1800:2400",
  "hoursFriday": "flex",
  "hoursSaturday": "off",
  "hoursSunday": "off"
}

class Request {
  name: string;
  hoursMonday?: string;
  hoursTuesday?: string;
  hoursWednesday?: string;
  hoursThursday?: string;
  hoursFriday?: string;
  hoursSaturday?: string;
  hoursSunday?: string;
}

Example success response:

{
  "status": "success",
  "result": "Company created successfully"
}

class Response {
  status: string;
  result: string;
}

Required fields

Field Type Validation Required Comment
name string 1 - 150 characters YES min:1 - max:150
hoursMonday string 200 characters NO off, flex, or dddd:dddd^dddd:dddd where d is single digit representing 24 hour clock
hoursTuesday string 200 characters NO off, flex, or dddd:dddd^dddd:dddd where d is single digit representing 24 hour clock
hoursWednesday string 200 characters NO off, flex, or dddd:dddd^dddd:dddd where d is single digit representing 24 hour clock
hoursThursday string 200 characters NO off, flex, or dddd:dddd^dddd:dddd where d is single digit representing 24 hour clock
hoursFriday string 200 characters NO off, flex, or dddd:dddd^dddd:dddd where d is single digit representing 24 hour clock
hoursSaturday string 200 characters NO off, flex, or dddd:dddd^dddd:dddd where d is single digit representing 24 hour clock
hoursSunday string 200 characters NO off, flex, or dddd:dddd^dddd:dddd where d is single digit representing 24 hour clock

The working hours are consisted of 4 digits, first 2 representing the hour and last 2 representing the minutes. Valid hour ranges 00-24 Valid minute ranges 00,10,20,30,40,50 For example if you want to define a range from 9:30am to 5:30pm you would need to do 0930:1730. Also if there is a need to set multiple working time intervals to indicate a lunch break you can do the following 0930:1230^1330:1730 where second time interval is separated from the first using the character ^. Other allowed values for working hours are flex if the department doesn't have a fixed working schedule, or off if the given day doesn not have working hours at all.

Update Department

PUT /company/:company-id:/departments/:department-id:

Request body

{
  "name": "Department Name",
  "hoursMonday": "0900:1200^1300:1700",
  "hoursTuesday": "0930:1230^1330:1730",
  "hoursWednesday": "0900:1200^1300:1700",
  "hoursThursday": "1400:1700^1800:2400",
  "hoursFriday": "flex",
  "hoursSaturday": "off",
  "hoursSunday": "off"
}

class Request {
  name: string;
  hoursMonday?: string;
  hoursTuesday?: string;
  hoursWednesday?: string;
  hoursThursday?: string;
  hoursFriday?: string;
  hoursSaturday?: string;
  hoursSunday?: string;
}

Example success response:

{
  "status": "success",
  "result": "Company created successfully"
}

class Response {
  status: string;
  result: string;
}

Required fields

Field type Validation optional description
name string 1 - 150 characters YES min:1 - max:150
hoursMonday string 200 characters NO off, flex, or dddd:dddd^dddd:dddd where d is single digit representing 24 hour clock
hoursTuesday string 200 characters NO off, flex, or dddd:dddd^dddd:dddd where d is single digit representing 24 hour clock
hoursWednesday string 200 characters NO off, flex, or dddd:dddd^dddd:dddd where d is single digit representing 24 hour clock
hoursThursday string 200 characters NO off, flex, or dddd:dddd^dddd:dddd where d is single digit representing 24 hour clock
hoursFriday string 200 characters NO off, flex, or dddd:dddd^dddd:dddd where d is single digit representing 24 hour clock
hoursSaturday string 200 characters NO off, flex, or dddd:dddd^dddd:dddd where d is single digit representing 24 hour clock
hoursSunday string 200 characters NO off, flex, or dddd:dddd^dddd:dddd where d is single digit representing 24 hour clock

The working hours are consisted of 4 digits, first 2 representing the hour and last 2 representing the minutes. Valid hour ranges 00-24 Valid minute ranges 00,10,20,30,40,50 For example if you want to define a range from 9:30am to 5:30pm you would need to do 0930:1730. Also if there is a need to set multiple working time intervals to indicate a lunch break you can do the following 0930:1230^1330:1730 where second time interval is separated from the first using the character ^. Other allowed values for working hours are flex if the department doesn't have a fixed working schedule, or off if the given day doesn not have working hours at all.

Get Department

GET /company/:company-id:/departments/:department-id:

Request body

{
  "status": "success",
  "result": {
    "id": "dep_i7as6dasi7d6aisd9",
    "name": "Default department",
    "hoursMonday": "0900:1200^1300:1700",
    "hoursTuesday": "0930:1230^1330:1730",
    "hoursWednesday": "0900:1200^1300:1700",
    "hoursThursday": "1400:1700^1800:2400",
    "hoursFriday": "flex",
    "hoursSaturday": "off",
    "hoursSunday": "off"
  }
}

class Response {
  status: string;
  result: [];
}

class Result {
  id: string;
  name: string;
  hoursMonday: string;
  hoursTuesday: string;
  hoursWednesday: string;
  hoursThursday: string;
  hoursFriday: string;
  hoursSaturday: string;
  hoursSunday: string;
}

This endpoint is protected by login.

List Departments

GET /company/:company-id:/departments/?page=1&pageSize=20?search=NAME

Example success response:

{
  "status": "success",
  "result": {
    "search": "NAME",
    "totalRecords": 1,
    "totalPages": 1,
    "currentPage": 1,
    "currentPageSize": 20,
    "departments": [
      {
        "id": "dep_as8dt86sdf8sd",
        "name": "Default department"
      }
    ]
  }
}

class Result {
  search?: string;
  totalRecords: number;
  totalPages: number;
  currentPage: number;
  currentPageSize: number;
  departments: Departments[];
}

class Departments {
  departmentId: string;
  departmentName: string;
}

Protected

Requires prior user login.

GET Parameters

parameter name type optional description
page int true this indicates the page number you request
pageSize int true the maximum records to be included in the page (default page size is 20)
search string true search keywords separated by space. By default matches each exact keyword. In case a more loose search is required simply add * at the end of the keyword. For example black* will match black and blackwater where black will match only black

Lists all departments for the company. The endpoint is protected behind login and requires the appropriate user authorisation/access level.

Employment details

Create employment

POST /company/:companyId:/users/:userId:/employment

Request body

{
  "departmentId": "**********",
  "title": "Senior Engineering Manager",
  "role": "MANAGER",
  "type": "FULL_TIME",
  "startDate": "2020-05-01",
  "hoursMonday": "flex",
  "hoursTuesday": "0010:0100^0200:0400",
  "hoursWednesday": "off",
  "hoursThursday": "0900:1200^1300:1700",
  "hoursFriday": "0900:1200^1300:1700",
  "hoursSaturday": "0900:1200^1300:1700",
  "hoursSunday": "0900:1200^1300:1700"
}

class Request {
  departmentId: string;
  title: string;
  role: string;
  type: string;
  startDate: date;
  hoursMonday: string;
  hoursTuesday: string;
  hoursWednesday: string;
  hoursThursday: string;
  hoursFriday: string;
  hoursSaturday: string;
  hoursSunday: string;
}

enum Relation {
  EMPLOYEE,
  MANAGER,
  TEAM_LEAD,
  CONTRACTOR,
  APPRENTICE,
  JUNIOR_EXECUTIVE,
  SENIOR_EXECUTIVE,
  DIRECTOR,
  NON_EXECUTIVE_DIRECTOR,
  OTHER
}

Example success response:

{
  "status": "success",
  "result": "Success message here"
}

class Response {
  status: string;
  result: string;
}

JSON fields

Field Type Validation Required Comment
departmentId string 1 - 60 characters YES
title string 1 - 60 characters YES employment title
role enum EMPLOYEE,MANAGER, TEAM_LEAD,CONTRACTOR, APPRENTICE,JUNIOR_EXECUTIVE,SENIOR_EXECUTIVE, DIRECTOR,NON_EXECUTIVE_DIRECTOR, OTHER YES should be one of the enum cases
type enum FULL_TIME,PART_TIME NO should be one of the enum cases
startDate string date YES Date of birth in format 'dd-mm-yyyy'
hoursMonday string 200 characters YES off, flex, or dddd:dddd^dddd:dddd where d is single digit representing 24 hour clock
hoursTuesday string 200 characters YES off, flex, or dddd:dddd^dddd:dddd where d is single digit representing 24 hour clock
hoursWednesday string 200 characters YES off, flex, or dddd:dddd^dddd:dddd where d is single digit representing 24 hour clock
hoursThursday string 200 characters YES off, flex, or dddd:dddd^dddd:dddd where d is single digit representing 24 hour clock
hoursFriday string 200 characters YES off, flex, or dddd:dddd^dddd:dddd where d is single digit representing 24 hour clock
hoursSaturday string 200 characters YES off, flex, or dddd:dddd^dddd:dddd where d is single digit representing 24 hour clock
hoursSunday string 200 characters YES off, flex, or dddd:dddd^dddd:dddd where d is single digit representing 24 hour clock

Other validations

Update employment

PUT /company/:companyId:/users/:userId:/employment

Request body

{
  "departmentId": "********",
  "title": "Backend Team Lead",
  "role": "TEAM_LEAD",
  "type": "FULL_TIME",
  "startDate": "2020-05-01",
  "hoursMonday": "flex",
  "hoursTuesday": "0010:0100^0200:0400",
  "hoursWednesday": "off",
  "hoursThursday": "0900:1200^1300:1700",
  "hoursFriday": "0900:1200^1300:1700",
  "hoursSaturday": "0900:1200^1300:1700",
  "hoursSunday": "0900:1200^1300:1700"
}

class Request {
  departmentId: string;
  title: string;
  role: string;
  type: string;
  startDate: date;
  hoursMonday: string;
  hoursTuesday: string;
  hoursWednesday: string;
  hoursThursday: string;
  hoursFriday: string;
  hoursSaturday: string;
  hoursSunday: string;
}

enum Relation {
  EMPLOYEE,
  MANAGER,
  TEAM_LEAD,
  CONTRACTOR,
  APPRENTICE,
  JUNIOR_EXECUTIVE,
  SENIOR_EXECUTIVE,
  DIRECTOR,
  NON_EXECUTIVE_DIRECTOR,
  OTHER
}

Example success response:

{
  "status": "success",
  "result": "Success message here"
}

class Response {
  status: string;
  result: string;
}

JSON fields

Field Type Validation Required Comment
departmentId string 1 - 60 characters YES
title string 1 - 60 characters YES employment title
role enum EMPLOYEE,MANAGER, TEAM_LEAD,CONTRACTOR, APPRENTICE,JUNIOR_EXECUTIVE,SENIOR_EXECUTIVE, DIRECTOR,NON_EXECUTIVE_DIRECTOR, OTHER YES should be one of the enum cases
type enum FULL_TIME,PART_TIME NO should be one of the enum cases
startDate string date YES Date of birth in format 'dd-mm-yyyy'
hoursMonday string 200 characters YES off, flex, or dddd:dddd^dddd:dddd where d is single digit representing 24 hour clock
hoursTuesday string 200 characters YES off, flex, or dddd:dddd^dddd:dddd where d is single digit representing 24 hour clock
hoursWednesday string 200 characters YES off, flex, or dddd:dddd^dddd:dddd where d is single digit representing 24 hour clock
hoursThursday string 200 characters YES off, flex, or dddd:dddd^dddd:dddd where d is single digit representing 24 hour clock
hoursFriday string 200 characters YES off, flex, or dddd:dddd^dddd:dddd where d is single digit representing 24 hour clock
hoursSaturday string 200 characters YES off, flex, or dddd:dddd^dddd:dddd where d is single digit representing 24 hour clock
hoursSunday string 200 characters YES off, flex, or dddd:dddd^dddd:dddd where d is single digit representing 24 hour clock

Other validations

Get employment

GET /company/:companyId:/users/:userId:/employment

Example success response:

{
   "status":"success",
   "result":{
      "title":"Name title update ",
      "role":"MANAGER",
      "status":"ACTIVE",
      "type":"FULL_TIME",
      "startDate":"2020-05-01T00:00:00.000000Z",
      "endDate":"2022-05-01T00:00:00.000000Z",
      "hoursMonday":"0900:1200^1300:1700",
      "hoursTuesday":"0900:1200^1300:1700",
      "hoursWednesday":"0900:1200^1300:1700",
      "hoursThursday":"0900:1200^1300:1700",
      "hoursFriday":"0900:1200^1300:1700",
      "hoursSaturday":"0900:1200^1300:1700",
      "hoursSunday":"0900:1200^1300:1700",
      "department":{
         "id":"dep_id_here",
         "name":"Department name"
      }
   }
}

class Result {
  title: string;
  role: string;
  status: string;
  type: string;
  startDate: string;
  endDate: string;
  hoursMonday: string;
  hoursTuesday: string;
  hoursWednesday: string;
  hoursThursday: string;
  hoursFriday: string;
  hoursSaturday: string;
  hoursSunday: string;
  department: Department;
}

class Department {
  id: string;
  name: string;
}

Lists all employment details. The endpoint is protected behind login and requires the appropriate user authorisation/access level.

Cease user employment.

DELETE /company/:companyId:/users/:userId:/employment

Example success response:

{
  "status": "success",
  "result": "Employment ceased"
}

class Responce {
  status: string;
  result: string;
}

Company modules state

GET /company/:companyId:/modules

Request body

Example success response:

{
  "status": "success",
  "result": [
    {
      "module": "LEAVE_MANAGEMENT",
      "isEnabled": true
    },
    {
      "module": "PAYROLL",
      "isEnabled": false
    },
    {
      "module": "RECRUITMENT",
      "isEnabled": false
    },
    {
      "module": "TIME_TRACKING",
      "isEnabled": false
    },
    {
      "module": "ROSTERS",
      "isEnabled": false
    }
  ]
}

class Response {
  status: string;
  result: Modules[];
}

Description

This endpoint will return the status and extra details (if any) for each company module. User must be logged in and part of the company they're requesting the module details.

Invoices

Get invoice details

POST /company/:companyId:/billing/invoices/:invoiceId:

Example success response:

{
  "status": "success",
  "result": {
    "id": "inv_1308dfa2de1a66618e69c9f55ee6bd",
    "month": 2,
    "year": 2023,
    "invoiceNumber": "INV-0000000001",
    "billTo": {
      "companyName": "alex company",
      "vatNumber": "",
      "address01": "",
      "address02": "",
      "stateCounty": "",
      "postCode": "",
      "country": "AFGHANISTAN"
    },
    "items": [
      {
        "name": "LEAVE_MANAGEMENT",
        "quantity": "3.00",
        "cost": "2.40",
        "amount": "7.20"
      }
    ],
    "subtotal": "7.20",
    "vatAmount": "1.66",
    "vatPercentage": "23.00",
    "total": "8.86",
    "currency": "EUR",
    "status": "OUTSTANDING",
    "createdAt": "2023-03-29T08:03:49.000000Z"
  }
}

class Response {
  status: string;
  result: Result;
}

class Result {
  id: string
  month: number
  year: number
  invoiceNumber: string
  billTo: BillTo[]
  items: Item[]
  subtotal: string
  vatAmount: string
  vatPercentage: string
  total: string
  currency: string
  status: string
  createdAt: string
}

class BillTo {
  companyName: string
  vatNumber: string
  address01: string
  address02: string
  stateCounty: string
  postCode: string
  country: string
}

class Item {
  name: string
  quantity: string
  cost: string
  amount: string
}

Details

This endpoint is protected and accessible only for administrators of the company. The response is going to contain the full details of the invoice requested.

List company invoices

GET /company/:company-id:/billing/invoices?page=1&pageSize=20

Example success response:

{
  "status": "success",
  "result": {
    "totalRecords": 2,
    "totalPages": 1,
    "currentPage": 0,
    "currentPageSize": 20,
    "result": [
      {
        "id": "inv_a1ce8037d4c3dfd1d7d39b63835b8e",
        "companyName": "alex company",
        "invoiceNumber": "INV-0000000001",
        "billingMonth": 2,
        "billingYear": 2023,
        "createdAt": "2023-02-22T11:02:40.000Z"
      },
      {
        "id": "inv_f9c91b704d6051b91f1463f88578cd",
        "companyName": "alex company",
        "invoiceNumber": "INV-0000000002",
        "billingMonth": 2,
        "billingYear": 2023,
        "createdAt": "2023-02-22T11:02:40.000Z"
      }
    ]
  }
}

class Result {
  totalRecords: number;
  totalPages: number;
  currentPage: number;
  currentPageSize: number;
  result: Result[];
}

class Result {
  id: string;
  companyName: string;
  invoiceNumber: string;
  billingMonth: number;
  billingYear: number;
  createdAt: date;
}

Description

This endpoint is protected and accessible only for administrators of the company. The response is going to contain a paginated list of all invoices generated for the given company.

Get current bill

GET /company/:companyId:/billing/current-bill

Example success response:

{
  "status":"success",
  "result":{
    "items":[
      {
      "moduleName": "LEAVE_MANAGEMENT",
      "costName": "Default",
      "quantity": 0.27,
      "unitCost": 2.83,
      "vatPercentage": 23,
      "amount": 0.75,
      "author": "john Doe",
      "currentDate": "2023-06-23T06:06:19.000000Z"
      }
    ]
  }
}

class Response {
  status: string;
  result: Result;
}

class Result {
  items: Items[];
}
class Items {
  moduleName: string;
  costName: string;
  quantity: number;
  unitCost: number;
  vatPercentage: number;
  amount: number;
  author: string;
  currentDate: date;

}

Details

This endpoint is protected and accessible only for administrators of the company. The response is going to contain the company current billing.

Company pricing

/company/:companyId:/billing/pricing

Example success response:

{
    "status": "success",
    "result": [
        {
            "module": "RECRUITMENT",
            "costName": "Default",
            "price": 1,
            "effectiveDate": "2023-03-01T00:00:00.000000Z"
        },
        {
            "module": "LEAVE_MANAGEMENT",
            "costName": "Default",
            "price": 2.83,
            "effectiveDate": "2022-08-01T00:00:00.000000Z"
        }
    ]
}

class Response {
  status: string;
  result: Result;
}

class Result {
  items: ModulePrice[];
}
class ModulePrice {
  module: Module;
  costName: string;
  price: number;
  effectiveDate: date;
}
enum Module {
  leaveManagement = "LEAVE_MANAGEMENT",
  payroll = "PAYROLL",
  recruitment = "RECRUITMENT",
  timeTracking = "TIME_TRACKING",
  rosters = "ROSTERS"
}

Provides company pricing for all enabled modules on the platform. It requires appropriate read access to the company pricing data. Access roles needed to use the endpoint are: admin, admin:read, company:admin or company:read User roles can be retrieved from User roles endpoint If the user making the request has unsufficient access within the company this endpoint will return response with status code Forbidden(403) and internal code 4002.

Leave management

All endpoints related to Leave Management module can be find here.

Enable/Disable module

POST /company/:company-id:/leave-management

{
  "action": "ENABLE",
  "password": "raw_admin_password"
}

class Request {
  action: Action;
  password: string;
}

enum Action {
  Enable = "ENABLE",
  Disable = "DISABLE",
}

Example success response:

{
  "status": "success",
  "result": "Success message here"
}

class Response {
  status: string;
  result: string;
}

Leave management module is disabled by default and needs to be enabled before users can be added to it and use it within the company.

This endpoint is used to enable or disable the Leave management module for the company. When enabled users can be added to the module and use it. Enabling the module alone will not accumulate any cost unless users are addded to the module.

It is also important to note that this endpoint is protected behind login and also requires module admin access plus the password of the user trying to enable ot disable the module.

Field name Type Required Comment
action enum YES allowed vallues are ENABLE or DISABLE
password string YES user raw password

An error will be returned if module is already in enabled state and you're trying to enable it again, and vice versa.

Leave type

Create leave type

POST /company/:company-id:/leave-management/leave-types

{
  "name": "name",
  "shortDescription": "shortDescription",
  "approvalType": "MANUAL",
  "takesFromPto": true,
  "hideFromCalendar": true,
  "paymentPercentage": 1,
  "color": "#65EE7B"
}

class Request {
  name: string;
  shortDescription: string;
  approvalType: ApprovalType;
  takesFromPto: boolean;
  hideFromCalendar: boolean;
  paymentPercentage: number;
  color: string;
}

enum ApprovalType {
  MANUAL = "MANUAL",
  AUTO_APPROVE = "AUTO_APPROVE",
}

Example success response:

{
  "status": "success",
  "result": {
    "id": "lt_1234",
    "name": "type name",
    "shortDescription": "shortDescription",
    "approvalType": "MANUAL",
    "takesFromPto": true,
    "hideFromCalendar": false,
    "paymentPercentage": 0,
    "color": "#65EE7B"
  }
}

class Response {
  status: string;
  result: [];
}

class Result {
  id: string;
  name: string;
  shortDescription: string;
  approvalType: string;
  takesFromPto: boolean;
  hideFromCalendar: boolean;
  paymentPercentage: number;
  color: string;
}
Field name Type Validation Required Comment
name string 2 - 100 characters YES Type name up to 100 characters
shortDescription string 1 - 150 characters NO Short leave type description. Up to 150 characters long
approvalType enum MANUAL/AUTO_APPROVE YES Allowed vallues are MANUAL or AUTO_APPROVE
takesFromPto boolean TRUE/FALSE NO If set to true it will deduct the days taken from the PTO allowance
hideFromCalendar boolean TRUE/FALSE NO If set to true it will be hidden from the company leaves calendar
paymentPercentage integer 0 - 100 NO Value between 0 and 100
color string HEX colour code NO Valid HEX colour code.

Leave management module must be enabled and the user making the request must be company or module administrator.

Update leave type

PUT /company/:company-id:/leave-management/leave-types/:leave-type-id:

{
  "name": "name",
  "shortDescription": "shortDescription",
  "approvalType": "MANUAL",
  "takesFromPto": true,
  "hideFromCalendar": true,
  "paymentPercentage": 1,
  "color": "#65EE7B"
}

class Request {
  name: string;
  shortDescription: string;
  approvalType: ApprovalType;
  takesFromPto: boolean;
  hideFromCalendar: boolean;
  paymentPercentage: number;
  color: string;
}

enum ApprovalType {
  MANUAL = "MANUAL",
  AUTO_APPROVE = "AUTO_APPROVE",
}

Example success response:

{
  "status": "success",
  "result": "Leave type updated"
}

class Response {
  status: string;
  result: string;
}
Field name Type Validation Required Comment
name string 2 - 100 characters YES Type name up to 100 characters
shortDescription string 1 - 150 characters NO Short leave type description. Up to 150 characters long
approvalType enum MANUAL/AUTO_APPROVE YES Allowed vallues are MANUAL or AUTO_APPROVE
takesFromPto boolean TRUE/FALSE NO If set to true it will deduct the days taken from the PTO allowance
hideFromCalendar boolean TRUE/FALSE NO If set to true it will be hidden from the company leaves calendar
paymentPercentage integer 0 - 100 NO Value between 0 and 100
color string HEX colour code NO Valid HEX colour code.

Leave management module must be enabled and the user making the request must be company or module administrator.

Get leave type

GET /company/:company-id:/leave-management/leave-types/:leave-type-id:

Example success response:

{
  "status": "success",
  "result": {
    "id": "lt_685435e278741572677b1674a41ba0",
    "name": "Name",
    "shortDescription": "description",
    "approvalType": "MANUAL",
    "takesFromPto": 1,
    "hideFromCalendar": 1,
    "paymentPercentage": 56,
    "color": "#65EE7B"
  }
}

class LeaveType {
  id: string;
  name: string;
  shortDescription: string;
  approvalType: ApprovalType;
  takesFromPto: boolean;
  hideFromCalendar: boolean;
  paymentPercentage: number;
  color: string;
}

This endpoint will return leave type for the company.

Get leave types

GET /company/:company-id:/leave-management/leave-types

Example success response:

{
  "status": "success",
  "result": [
    {
      "id": "lt_1ae56a20e24f11ec8fea0242ac18",
      "name": "Holiday",
      "color": "#E76F3D"
    }
  ]
}

class LeaveType {
  id: string;
  name: string;
  color: string;
}

This endpoint will return all leave types for the company. Some preconditions must be met in order to access this

Delete leave type

DELETE /company/:company-id:/leave-management/leave-types/:leave-type-id:

Example success response:

{
  "status": "success",
  "result": "Leave type deleted"
}

class Response {
  status: string;
  result: string;
}

This endpoint will delete leave type for the company.

Company

Get year start month

GET /company/:company-id:/leave-management/parameters

Example success response:

{
  "status": "success",
  "result": {
    "yearStartMonth": 1,
    "workingSchedule": "MONDAY_TO_FRIDAY"
  }
}

class Response {
  status: string;
  result: Result;
}

class Result {
  yearStartMonth: number;
  workingSchedule: string;
}

Leave management module must be enabled and the user making the request must be company or module administrator.

Update year start month

PUT /company/:company-id:/leave-management/parameters

{
  "yearStartMonth": 1,
  "workingSchedule": "MONDAY_TO_FRIDAY"
}

class Request {
  yearStartMonth: number;
  workingSchedule: string
}

Example success response:

{
  "status": "success",
  "result": "Leave type updated"
}

class Response {
  status: string;
  result: string;
}
Field name Type Validation Required Comment
yearStartMonth integer 1 - 12 YES Value between 1 and 12
workingSchedule enum string YES allowed vallues are MONDAY_TO_FRIDAY or EMPLOYEE_SCHEDULE

Leave management module must be enabled and the user making the request must be company or module administrator.

User

Add User to leave

POST /company/:company-id:/leave-management/users/:user-id:

{
  "role": "USER",
  "canCarryOverDays": true,
  "maxCarryOverDays": 1.1,
  "carryOverMonthsAfterYearEnd": 1,
  "ptoAllowance": 2.1,
  "canExceedPtoAllowance": true
}

class Request {
  role: ApprovalType;
  canCarryOverDays: boolean;
  maxCarryOverDays: float;
  carryOverMonthsAfterYearEnd: number;
  ptoAllowance: float;
  canExceedPtoAllowance: boolean;
}

enum ApprovalType {
  USER = "USER",
  APPROVER = "APPROVER",
}

Example success response:

{
  "status": "success",
  "result": "User added to leave management"
}

class Response {
  status: string;
  result: [];
}
Field name Type Validation Required Comment
role enum USER/APPROVER YES Allowed vallues are USER or APPROVER
canCarryOverDays boolean TRUE/FALSE NO If set to true it will the user to carry over days
maxCarryOverDays fload 0 - 365 NO If set to true it will it will set the limit of carry over days
carryOverMonthsAfterYearEnd number 1-11 NO Set the carry over months after company year end
ptoAllowance fload 1 - 365 YES Set user PTO days
canExceedPtoAllowance boolean TRUE/FALSE NO Allow the user to exceed PTO

Leave management module must be enabled and the user making the request must be company or module administrator.

List all users

GET /company/:company-id:/leave-management/users?page=1&pageSize=12&search=John

{
  "status": "success",
  "result": {
    "search": "John",
    "totalRecords": 1,
    "totalPages": 1,
    "currentPage": 0,
    "currentPageSize": 20,
    "result": [
      {
        "id": "usr_b762fd848fba96bed5e4dd445adb98",
        "firstName": "John",
        "lastName": "Doe",
        "email": "[email protected]"
      }
    ]
  }
}

Example success response:

class Result {
  search?: string;
  totalRecords: number;
  totalPages: number;
  currentPage: number;
  currentPageSize: number;
  result: User[];
}

class User {
  id: string;
  firstName: string;
  lastName: string;
  email: string;
}

GET Parameters

parameter name type optional description
page int true this indicates the page number you request
pageSize int true the maximum records to be included in the page (default page size is 20)
search string true search keywords separated by space. By default matches each exact keyword. In case a more loose search is required simply add * at the end of the keyword. For example black* will match black and blackwater where black will match only black

Lists all users added to the module. The endpoint is protected behind login and requires the appropriate user authorisation/access level.

Update User to leave

PUT /company/:company-id:/leave-management/users/:user-id:

{
  "role": "USER",
  "canCarryOverDays": true,
  "maxCarryOverDays": 1.1,
  "carryOverMonthsAfterYearEnd": 1,
  "ptoAllowance": 2.1,
  "canExceedPtoAllowance": true
}

class Request {
  role: ApprovalType;
  canCarryOverDays: boolean;
  maxCarryOverDays: float;
  carryOverMonthsAfterYearEnd: number;
  ptoAllowance: float;
  canExceedPtoAllowance: boolean;
}

enum ApprovalType {
  USER = "USER",
  APPROVER = "APPROVER",
}

Example success response:

{
  "status": "success",
  "result": "Update user data in leave management"
}

class Response {
  status: string;
  result: [];
}
Field name Type Validation Required Comment
role enum USER/APPROVER YES Allowed vallues are USER or APPROVER
canCarryOverDays boolean TRUE/FALSE NO If set to true it will the user to carry over days
maxCarryOverDays fload 0 - 365 NO If set to true it will it will set the limit of carry over days
carryOverMonthsAfterYearEnd number 1-11 NO Set the carry over months after company year end
ptoAllowance fload 1 - 365 YES Set user PTO days
canExceedPtoAllowance boolean TRUE/FALSE NO Allow the user to exceed PTO

Leave management module must be enabled and the user making the request must be company or module administrator.

User leave settings

GET /company/:company-id:/leave-management/users/:user-id:

Example success response:

{
  "status": "success",
  "result": {
    "role": "APPROVER",
    "isActive": false,
    "dateAdded": "2022-06-10T12:14:58.000000Z",
    "dateCeased": "2022-06-21T09:28:27.000000Z",
    "canCarryOverDays": true,
    "maxCarryOverDays": 5,
    "carryOverMonthsAfterYearEnd": 1,
    "ptoAllowance": 0,
    "canExceedPtoAllowance": true
  }
}

class Response {
  status: string;
  result: UserLeaveSettings;
}

class UserLeaveSettings {
  role: string;
  isActive: boolean;
  dateAdded: string;
  dateCeased?: string;
  canCarryOverDays: boolean;
  maxCarryOverDays: number;
  carryOverMonthsAfterYearEnd?: number;
  ptoAllowance: number;
  canExceedPtoAllowance: boolean;
}

This endpoint will return all relevant details for a user that was previously added to the leave management module.

User leave summary

GET /company/:company-id:/leave-management/users/:user-id:/leave-summary

Example success response:

{
  "status": "success",
  "result": {
    "id": "lua_efg838",
    "firstName": "John",
    "lastName": "Doe",
    "carryOverDaysTaken": 3,
    "ptoDaysBooked": 10,
    "ptoDaysRequested": 2,
    "ptoAllowance": 20,
    "year": 2023
  }
}

class Leave {
  id: string;
  firstName: string;
  lastName: string;
  carryOverDaysTaken: number;
  ptoDaysBooked: number;
  ptoDaysRequested: number;
  ptoAllowance: number;
  year: number
}

GET Parameters

parameter name type optional description
year number true Insert valid Year as get parameter

Returns a specific user summary for leave management module. The endpoint is protected behind login and requires the appropriate user authorisation/access level.

List users leave summary

GET /company/:company-id:/leave-management/users/leave-summary?page=1&pageSize=12&year=2023&departmentId=: department-id:

Example success response:

{
  "status": "success",
  "result": {
    "year": 2023,
    "totalRecords": 1,
    "totalPages": 1,
    "currentPage": 0,
    "currentPageSize": 20,
    "result": [
      {
        "id": "lua_efg838",
        "firstName": "John",
        "lastName": "Doe",
        "carryOverDaysTaken": 3,
        "ptoDaysBooked": 10,
        "ptoDaysRequested": 2,
        "ptoAllowance": 20,
        "year": 2023
      }
    ]
  }
}

class Response {
  status: string;
  result: Leave;
}

class Leave {
  id: string;
  firstName: string;
  lastName: string;
  carryOverDaysTaken: number;
  ptoDaysBooked: number;
  ptoDaysRequested: number;
  ptoAllowance: number;
  year: number
}

GET Parameters

parameter name type optional description
page int true this indicates the page number you request
pageSize int true the maximum records to be included in the page (default page size is 20)
year number true Insert valid Year in the search
department string true You cane set the department id in the search

Lists all users added to the module. The endpoint is protected behind login and requires the appropriate user authorisation/access level.

Remove user from leave

DELETE /company/:company-id:/leave-management/users/:user-id:

Example success response:

{
  "status": "success",
  "result": "User data updated"
}

class Response {
  status: string;
  result: UserLeaveSettings;
}

This endpoint will remove the user from leave management module.

Public holidays

List generic holidays

GET /company/:company-id:/leave-management/public-holidays?year=2022&countryCode=IE

{
  "status": "success",
  "result": {
    "year": 2022,
    "countryCode": "IE",
    "holidays": [
      {
        "date": "2022-01-01",
        "name": "New Year's Day"
      },
      {
        "date": "2022-03-18",
        "name": "Day of Rememberance and Recognition"
      }
    ]
  }
}

Example success response:

class Response {
  status: string;
  result: Result[];
}

class Result {
  year: number;
  countryCode: string;
  holidays: Holiday[]
}

class Holiday {
  name: string;
  date: date;
}

GET Parameters

parameter name type optional description
year string true Year parameter YYYY-MM-DD
countryCode string true Country Codes ISO Alpha-2

Lists all public holidays for the module. The endpoint is protected behind login and requires the appropriate user authorisation/access level.

Get company holidays

GET /company/:company-id:/leave-management/company-holidays?year=2022

{
  "status": "success",
  "result": [
    {
      "name": "Holiday 1",
      "date": "2022-01-01"
    },
    {
      "name": "Holiday 2",
      "date": "2022-01-02"
    }
  ]
}

Example success response:

class Response {
  status: string;
  result: Result[];
}

class Result {
  name: string;
  date: date;
}

GET Parameters

parameter name type optional description
year string true Year parameter YYYY

Lists all company holidays for the module. The endpoint is protected behind login and requires the appropriate user authorisation/access level.

Add holiday to company

POST /company/:company-id:/leave-management/public-holidays

{
  "holidays": [
    {
      "date": "2022-01-01",
      "name": "Holiday 1"
    },
    {
      "date": "2022-01-02",
      "name": "Holiday 2"
    },
    {
      "date": "2022-01-03",
      "name": "Holiday 3"
    }
  ]
}

Example success response:

class Request {
  holidays: string[];
}

class Holidays {
  date: date;
  name: string;
}
parameter name type optional description
year string false Year parameter YYYY-MM-DD
name string false Holiday name

Create company holiday . The endpoint is protected behind login and requires the appropriate user authorisation/access level.

Leave request

Calculate PTO days

POST /company/:company-id:/leave-management/users/:user-id:/requests/calculate-pto

{
  "leaveTypeId": "lt_uuid",
  "startDate": "2022-01-27",
  "startTime": "START_OF_DAY",
  "endDate": "2022-02-10",
  "endTime": "END_OF_DAY"
}

class Request {
  leaveTypeId: string;
  startDate: date;
  startTime: StartTime;
  endDate: date;
  endTime: EndTime;
}

enum StartTime {
  START_OF_DAY = "START_OF_DAY",
  MIDDAY = "MIDDAY"
}

enum EndTime {
  MIDDAY = "MIDDAY",
  END_OF_DAY = "END_OF_DAY"
}

Example success response:

{
  "status": "success",
  "result": {
    "pto": 9
  }
}

class Response {
  status: string;
  result: Result;
}

class Result {
  pto: number;
}
Field name Type Required Comment
leaveTypeId string YES Type uuid leaveTypeId 1 - 60 characters
startDate string YES Year parameter YYYY-MM-DD
startTime string YES Allowed vallues are START_OF_DAY or MIDDAY
endDate string YES Year parameter YYYY-MM-DD
endTime string YES Allowed vallues are MIDDAY or END_OF_DAY

This endpoint will only calculate how many days of PTO will potentially take a leave request for a certain user with specified parameters. Leave management module must be enabled and the user making the request must be part of the company or module administrator or add as employee.

Create leave request

POST /company/:company-id:/leave-management/users/:user-id:/requests

{
  "leaveTypeId": "lt_uuid",
  "startDate": "2022-01-27",
  "startTime": "START_OF_DAY",
  "endDate": "2022-02-10",
  "endTime": "END_OF_DAY",
  "message": "text message"
}

class Request {
  leaveTypeId: string;
  startDate: string;
  startTime: StartTime;
  endDate: string;
  endTime: EndTime;
  message: string;
}

enum StartTime {
  START_OF_DAY = "START_OF_DAY",
  MIDDAY = "MIDDAY"
}

enum EndTime {
  MIDDAY = "MIDDAY",
  END_OF_DAY = "END_OF_DAY"
}

Example success response:

{
  "status": "success",
  "result": "Leave request recorded"
}

class Response {
  status: string;
  result: [];
}

class Result {
  status: string;
  result: string;
}
Field name Type Required Comment
leaveTypeId string YES Type uuid leaveTypeId 1 - 60 characters
startDate string YES Year parameter YYYY-MM-DD
startTime string YES Allowed vallues are START_OF_DAY or MIDDAY
endDate string YES Year parameter YYYY-MM-DD
endTime string YES Allowed vallues are MIDDAY or END_OF_DAY
message string NO Maximum string length is 150,

Leave management module must be enabled and the user making the request must be part of the company or module administrator or add as employ.

Get leave request data

GET /company/:company-id:/leave-management/requests/:request-id:

Example success response:

{
  "status": "success",
  "result": {
    "id": "lr_203bbb0b8abd5c34baf68f153b8048",
    "startDate": "2022-03-01",
    "startTime": "START_OF_DAY",
    "endDate": "2022-03-05",
    "endTime": "END_OF_DAY",
    "status": "SUBMITTED",
    "ptoDaysTaken": "4.5",
    "leaveTypeName": "Type1",
    "employeeMessage": "message text",
    "approverComment": "",
    "firstName": "john",
    "lastName": "Doe",
    "departmentName": "Department1",
    "hideFromCalendar": true,
    "createdBy": "john Doe",
    "updatedBy": "john Doe",
    "createdAt": "2022-10-05T11:02:40.000Z",
    "updatedAt": "2022-10-05T11:02:40.000Z"
  }
}

class Result {
  id: string;
  startDate: date;
  startTime: StartTime;
  endDate: date;
  endTime: EndTime;
  status: Status;
  ptoDaysTaken: number;
  leaveTypeName: string;
  employeeMessage: string;
  approverComment: string;
  firstName: string;
  lastName: string;
  departmentName: string;
  hideFromCalendar: boolean;
  createdBy: string;
  updatedBy: string;
  createdAt?: date;
  updatedAt?: date;
}

enum StartTime {
  START_OF_DAY = "START_OF_DAY",
  MIDDAY = "MIDDAY"
}

enum EndTime {
  MIDDAY = "MIDDAY",
  END_OF_DAY = "END_OF_DAY"
}

enum Status {
  APPROVED = "APPROVED",
  CANCELLED = "CANCELLED",
  DECLINED = "DECLINED"
}

Leave management module must be enabled and the user making the request must be part of the company, added to the leave management module with administrator role or set as approver.

Get all user leave requests

GET /company/:company-id:/leave-management/users/:user-id:/requests?year=2022&month=10&status=APPROVED

Example success response:

{
  "status": "success",
  "result": {
    "year": 2022,
    "month": 1,
    "status": "SUBMITTED",
    "result": [
      {
        "id": "lr_123",
        "userId": "usr_sa78dsad978agsdb0a",
        "firstName": "john",
        "lastName": "Doe",
        "ptoDaysTaken": "3.0",
        "leaveTypeName": "leave_type_name",
        "startDate": "2022-02-11",
        "startTime": "MIDDAY",
        "endDate": "2022-02-13",
        "endTime": "END_OF_DAY",
        "status": "SUBMITTED",
        "departmentName": "departmentName",
        "color": "#65EE7B",
        "hideFromCalendar": true,
        "createdAt": "2022-10-12T14:54:07.000Z"
      }
    ]
  }
}

class Result {
  year: number;
  month: number;
  status: string;
  result: Leave[];
}

class Leave {
  id: string;
  userId: string;
  firstName: string;
  lastName: string;
  ptoDaysTaken: number;
  leaveTypeName: string;
  startDate: date;
  startTime: StartTime;
  endDate: date;
  endTime: EndTime;
  status: Status;
  departmentName: string;
  color: string;
  hideFromCalendar: boolean;
  createdAt: date;
}

enum StartTime {
  START_OF_DAY = "START_OF_DAY",
  MIDDAY = "MIDDAY"
}

enum EndTime {
  MIDDAY = "MIDDAY",
  END_OF_DAY = "END_OF_DAY"
}

enum Status {
  SUBMITTED = "SUBMITTED",
  AUTO_APPROVED = "AUTO_APPROVED",
  APPROVED = "APPROVED",
  CANCELLED = "CANCELLED",
  DECLINED = "DECLINED"
}
Field name Type Required Comment
year string NO Year parameter Y
month string NO Month paramenter M
status string NO The request status SUBMITTED ,AUTO_APPROVED,APPROVED,CANCELLED,DECLINED

Leave management module must be enabled and the user making the request must be part of the company, added to the leave management module with administrator role or set as approver.This will return all user requests.

Get all leave requests

GET /company/:company-id: /leave-management/requests?departmentId=dp_123&year=2022&month=10&status=APPROVED

Example success response:

{
  "status": "success",
  "result": {
    "year": 2022,
    "month": 3,
    "departmentId": "dp_123",
    "status": "SUBMITTED",
    "result": [
      {
        "id": "lr_123",
        "firstName": "john",
        "lastName": "Doe",
        "ptoDaysTaken": "3.0",
        "leaveTypeName": "leave_type_name",
        "startDate": "2022-02-11",
        "startTime": "MIDDAY",
        "endDate": "2022-02-13",
        "endTime": "END_OF_DAY",
        "status": "SUBMITTED",
        "departmentName": "departmentName",
        "color": "#65EE7B",
        "hideFromCalendar": true,
        "createdAt": "2022-10-12T14:54:07.000Z"
      }
    ]
  }
}

class Result {
  year: number;
  month: number;
  departmentId: string;
  status: string;
  result: Leave[];
}

class Leave {
  id: string;
  firstName: string;
  lastName: string;
  ptoDaysTaken: number;
  leaveTypeName: string;
  startDate: date;
  startTime: StartTime;
  endDate: date;
  endTime: EndTime;
  status: Status;
  departmentName: string;
  color: string;
  hideFromCalendar: boolean;
  createdAt: date;
}

enum StartTime {
  START_OF_DAY = "START_OF_DAY",
  MIDDAY = "MIDDAY"
}

enum EndTime {
  MIDDAY = "MIDDAY",
  END_OF_DAY = "END_OF_DAY"
}

enum Status {
  SUBMITTED = "SUBMITTED",
  AUTO_APPROVED = "AUTO_APPROVED",
  APPROVED = "APPROVED",
  CANCELLED = "CANCELLED",
  DECLINED = "DECLINED"
}
Field name Type Required Comment
departmentId string NO Type uuid departmentId 1 - 60 characters
year string NO Year parameter Y
month string NO Month paramenter M
status string NO The request status SUBMITTED ,AUTO_APPROVED,APPROVED,CANCELLED,DECLINED

Leave management module must be enabled and the user making the request must be part of the company, added to the leave management module with administrator role or set as approver.

Update leave request

PUT /company/:company-id:/leave-management/requests/:request-id:

{
  "status": "status",
  "comment": "comment text"
}

class Request {
  status: Status;
  comment: string;
}

enum Status {
  APPROVED = "APPROVED",
  CANCELLED = "CANCELLED",
  DECLINED = "DECLINED"
}

Example success response:

{
  "status": "success",
  "result": "Leave request update success"
}

class Result {
  status: string;
  result: string;
}
Field name Type Required Comment
status string YES Allowed vallues are APPROVED,CANCELLED or DECLINED
comment string NO Maximum string length is 150,

Leave management module must be enabled and the user making this request must hold company admin, module admin role, or be added to the module as approver to perform this action.

List all pending requests

GET /company/:company-id:/leave-management/users/pending-requests?page=1&pageSize=12&departmentId=dp_123qwe

Example success response:

{
  "status": "success",
  "result": {
    "departmentId": "dp_123qwe",
    "totalRecords": 1,
    "totalPages": 1,
    "currentPage": 0,
    "currentPageSize": 20,
    "result": [
      {
        "id": "lr_84967e8a378ac56668d99e1a9901a0",
        "startDate": "2022-02-11",
        "startTime": "START_DATE",
        "endDate": "2022-02-13",
        "endTime": "MIDDAY",
        "status": "SUBMITTED",
        "ptoDaysTaken": "1.5",
        "leaveTypeName": "Type1",
        "firstName": "john",
        "lastName": "Doe",
        "departmentName": "Department1"
      }
    ]
  }
}

class Result {
  departmentId?: string;
  totalRecords: number;
  totalPages: number;
  currentPage: number;
  currentPageSize: number;
  result: Leave[];
}

class Leave {
  id: string;
  startDate: date;
  startTime: StartTime;
  endDate: date;
  endTime: EndTime;
  status: Status;
  ptoDaysTaken: number;
  leaveTypeName: string;
  firstName: string;
  lastName: string;
  departmentName: string;
}

enum StartTime {
  START_OF_DAY = "START_OF_DAY",
  MIDDAY = "MIDDAY"
}

enum EndTime {
  MIDDAY = "MIDDAY",
  END_OF_DAY = "END_OF_DAY"
}

enum Status {
  APPROVED = "APPROVED",
  CANCELLED = "CANCELLED",
  DECLINED = "DECLINED"
}
Field name Type Required Comment
page int NO this indicates the page number you request
pageSize int NO the maximum records to be included in the page (default page size is 20)
departmentUuid string NO Department filter

Leave management module must be enabled and the user making this request must hold company admin, module admin role, or be added to the module as approver to perform this action. This endpoint will return all pending leave requests.

User get leave requests

GET /company/:company-id:/leave-management/users/user-id/requests/request-id

Example success response:

{
  "status": "success",
  "result": {
    "id": "lr_md8fgadfgd0f87dfga9",
    "startDate": "2022-03-01",
    "startTime": "START_OF_DAY",
    "endDate": "2022-03-10",
    "endTime": "END_OF_DAY",
    "status": "SUBMITTED",
    "ptoDaysTaken": "9.0",
    "leaveTypeName": "Type1",
    "employeeMessage": "VARCHAR 150",
    "approverComment": "",
    "firstName": "john",
    "lastName": "Doe",
    "email": "[email protected]",
    "departmentName": "Department1",
    "hideFromCalendar": true,
    "createdBy": "john Doe",
    "updatedBy": "john Doe",
    "createdAt": "2022-11-10T16:52:27.000000Z"
  }
}

class Result {
  id: string;
  startDate: date;
  startTime: StartTime;
  endDate: date;
  endTime: EndTime;
  status: Status;
  ptoDaysTaken: number;
  leaveTypeName: string;
  employeeMessage: string;
  approverComment: string;
  firstName: string;
  lastName: string;
  email: string;
  departmentName: string;
  hideFromCalendar: boolean;
  createdBy: string;
  updatedBy: string;
  createdAt: date;
}

enum StartTime {
  START_OF_DAY = "START_OF_DAY",
  MIDDAY = "MIDDAY"
}

enum EndTime {
  MIDDAY = "MIDDAY",
  END_OF_DAY = "END_OF_DAY"
}

enum Status {
  SUBMITTED = "SUBMITTED",
  AUTO_APPROVED = "AUTO_APPROVED",
  APPROVED = "APPROVED",
  CANCELLED = "CANCELLED",
  DECLINED = "DECLINED"
}

Leave management module must be enabled and the user making the request must be part of the company, added to the leave management module. And to be the user has on the leave request.

User cancel leave requests

PUT /company/:company-id:/leave-management/users/user-id/requests/request-id

{
  "status": "status",
  "comment": "The request was canceled"
}

class Request {
  status: Status;
  comment: string;
}

Leave management module must be enabled and the user making the request must be part of the company, added to the leave management module. And to be the user has on the leave request.

Assets & Inventory

Create asset

POST /company/:company-id:/assets

Request body

{
  "typeId": "d1Z6RGYyVlRqaGRoeTNBMVJ3M2MxZz09",
  "name": "Asset name",
  "reference": "801238da",
  "condition": 4,
  "userId": "usr_uuid"
}

class Request {
  typeId: string;
  name: string;
  reference: string;
  condition: number;
  userId?: string;
}

Example success response:

{
  "status": "success",
  "result": "Company asset created"
}

class Response {
  status: string;
  result: string;
}

Protected

Requires prior user login and user be part of the company with admin rights for the assets and inventory module

Required fields

Field Type Validation Comment
typeId string 1 - 100 characters hash of item type id
name string 1 - 100 characters the name of the asset item
reference string 1 - 50 characters reference is the unick number
condition number 0 - 5 from 1 to 5
userId string 1 - 50 characters adding the user id is gonna add the item to the user

The endpoint is protected behind login and requires the appropriate user authorisation/access level

Update asset

PUT /company/:company-id:/assets/:asset-id:

Request body

{
  "typeId": "d1Z6RGYyVlRqaGRoeTNBMVJ3M2MxZz09",
  "name": "Asset name",
  "reference": "801238da",
  "condition": 4
}

class Request {
  typeId: string;
  name: string;
  reference: string;
  condition: number;
}

Example success response:

{
  "status": "success",
  "result": "Asset updated"
}

class Response {
  status: string;
  result: string;
}

Protected

Requires prior user login and user be part of the company with admin rights for the assets and inventory module

Required fields

Field Type Validation Comment
typeId string 1 - 100 characters hash of item type id
name string 1 - 100 characters the name of the asset item
reference string 1 - 50 characters reference is the unick number
condition number 0 - 5 from 1 to 5

The endpoint is protected behind login and requires the appropriate user authorisation/access level

Assign asset to user

PUT /company/:company-id:/assets/:asset-id:/assign/:user-id:

Example success response:

{
  "status": "success",
  "result": "Asset assigned"
}

class Result {
  status: string;
  result: string;
}

The endpoint is protected behind login and requires the appropriate user authorisation/access level

Returned asset

PUT /company/:company-id:/assets/:asset-id:/returned:

Request body

{
  "condition": 4
}

class Request {
  condition: number;
}

Example success response:

{
  "status": "success",
  "result": "Asset returned"
}

class Result {
  status: string;
  result: string;
}

Required fields

Field Type Validation Comment
condition number 0 - 5 from 1 to 5

The endpoint is protected behind login and requires the appropriate user authorisation/access level

Retired asset

PUT /company/:company-id:/assets/:asset-id:/retired

Example success response:

{
  "status": "success",
  "result": "Asset is retired"
}

class Result {
  status: string;
  result: string;
}

The endpoint is protected behind login and requires the appropriate user authorisation/access level

List assets

GET /company/:company-id:/assets?page=1&pageSize=12

Example success response:

{
  "status": "success",
  "result": {
    "search": "John",
    "totalRecords": 1,
    "totalPages": 1,
    "currentPage": 0,
    "currentPageSize": 20,
    "result": [
      {
        "id": "85b63f042f7341e76e10a71254913",
        "companyId": "com_a85b63f042f7341e76e10a71254913",
        "type": "Software",
        "assignedTo": "User 2 Last",
        "description": "riko 3",
        "reference": "kob123",
        "condition": 4,
        "status": "AVAILABLE",
        "dateAssigned": "2023-01-10T00:00:00.000000Z",
        "dateReturned": "2023-11-10T00:00:00.000000Z"
      }
    ]
  }
}

class Result {
  totalRecords: number;
  totalPages: number;
  currentPage: number;
  currentPageSize: number;
  search?: string;
  typeId?: string;
  status?: string;
  result: Result[];
}
class Result {
  id: string;
  companyId: string;
  type: string;
  assignedTo: string;
  description: string;
  reference: string;
  condition: number;
  status: string;
  dateAssigned: date;
  dateReturned: date;
}

GET Parameters

parameter name type optional description
page int true this indicates the page number you request
pageSize int true the maximum records to be included in the page (default page size is 20)
search string true the item name or reference
typeId string true is optional and expecting asset typeId value
status enum true should be one of the following enum cases ASSIGNED, AVAILABLE or RETIRED

Lists all assets to the module. The endpoint is protected behind login and requires the appropriate user authorisation/access level.

Get asset details

GET /company/:company-id:/assets/:asset-id:

Example success response:

{
  "status": "success",
  "result": {
        "id": "85b63f042f7341e76e10a71254913",
        "companyId": "com_a85b63f042f7341e76e10a71254913",
        "type": "Software",
        "assignedTo": "User 2 Last",
        "description": "riko 3",
        "reference": "kob123",
        "condition": 4,
        "status": "AVAILABLE",
        "dateAssigned": "2023-01-10T00:00:00.000000Z",
        "dateReturned": "2023-11-10T00:00:00.000000Z"
  }
}


class Result {
  id: string;
  companyId: string;
  type: string;
  assignedTo: string;
  description: string;
  reference: string;
  condition: number;
  status: string;
  dateAssigned: date;
  dateReturned: date;
}

Lists asset details. The endpoint is protected behind login and requires the appropriate user authorisation/access level.

Assets history

GET /company/:company-id:/assets/:asset-id:/history?page=1&pageSize=12

Example success response:

{
  "status": "success",
  "result": {
    "totalRecords": 1,
    "totalPages": 1,
    "currentPage": 0,
    "currentPageSize": 20,
    "result": [
      {
        "assetId": "85b63f042f7341e76e10a71254913",
        "description": "Item create: riko sad as 1 | Condition: 4 | Reference: 00123",
        "createdBy": "john Doe",
        "updatedBy": "HR Omni Administrator",
        "createdAt": "2023-11-10T00:00:00.000000Z"
      }
    ]
  }
}

class Result {
  totalRecords: number;
  totalPages: number;
  currentPage: number;
  currentPageSize: number;
  result: Result[];
}
class Result {
  assetId: string;
  description: string;
  createdBy: string;
  updatedBy: string;
  dateReturned: date;
}

GET Parameters

parameter name type optional description
page int true this indicates the page number you request
pageSize int true the maximum records to be included in the page (default page size is 20)

Lists all asset history. The endpoint is protected behind login and requires the appropriate user authorisation/access level.

Create asset type

POST /company/:company-id:/assets/types

Request body

{
  "name": "Type name"
}

class Request {
  name: string;
}

Example success response:

{
  "status": "success",
  "result":
      {
        "id": "85b63f042f7341e76e10a71254913",
        "type": "type name"
      }
}

class Result {
  status: string;
  result: Result;
}
class Result {
  id: string;
  type: string;
}

Required fields

Field Type Validation Comment
name string 1 - 50 characters the name of the asset type

The endpoint is protected behind login and requires the appropriate user authorisation/access level

Update asset type

PUT /company/:company-id:/assets/types/:type-id:

Request body

{
  "name": "Type name update"
}

class Request {
  name: string;
}

Example success response:

{
  "status": "success",
  "result":
      {
        "id": "idhi2bdb22hd2o2234",
        "type": "type name"
      }
}

class Result {
  status: string;
  result: Result;
}
class Result {
  id: string;
  type: string;
}

Required fields

Field Type Validation Comment
name string 1 - 50 characters the name of the asset type

The endpoint is protected behind login and requires the appropriate user authorisation/access level

List types

GET /company/:company-id:/assets/types

Example success response:

{
  "status": "success",
  "result":[
      {
        "id": "85b63f042f7341e76e10a71254913",
        "isDefault": true,
        "type": "type name"
      }
    ]
}

class Result {
  status: string;
  result: Result[];
}
class Result {
  id: string;
  isDefault: boolean;
  type: string;
}

Lists all assets types to the module. The endpoint is protected behind login and requires the appropriate user authorisation/access level.

User assets

GET /company/:company-id:/users/:user-id:/assets

Example success response:

{
  "status": "success",
  "result":[
      {
        "assetId": "TWUvcGxPdjdiU2dkT2JUa0tEdlRnUT09",
        "assignedTo": "Jon Do",
        "description": "asset name",
        "type": "type name",
        "reference": "09876",
        "condition": 4,
        "status": "ASSIGNED",
        "dateAssigned": "2023-03-22T10:46:47.000000Z"
      }
    ]
}

class Result {
  status: string;
  result: Result[];
}
class Result {
  assetId: string;
  assignedTo: string;
  description: string;
  type: string;
  refference: string;
  condition: number;
  status: string;
  dateAssigned: date;
}

Lists all assets types to the module. The endpoint is protected behind login and requires the appropriate user authorisation/access level.

Time Tracking

Enable/Disable module

POST /company/:company-id:/time-tracking

{
  "action": "ENABLE",
  "password": "raw_admin_password"
}

class Request {
  action: Action;
  password: string;
}

enum Action {
  Enable = "ENABLE",
  Disable = "DISABLE",
}

Example success response:

{
  "status": "success",
  "result": "Success message here"
}

class Response {
  status: string;
  result: string;
}

Time tracking module is disabled by default and needs to be enabled before it can be used. Once enabled, users can start tracking their time. Users won't need to be specifically added to the module.

Enabling the module alone will not accumulate any cost unless users start tracking their time.

It is also important to note that this endpoint is protected behind login and also requires module admin access plus the password of the user trying to enable ot disable the module.

Field name Type Required Comment
action enum YES allowed vallues are ENABLE or DISABLE
password string YES user raw password

An error will be returned if module is already in enabled state and you're trying to enable it again, and vice versa.

Time tracking parameters

Get time tracking parameters

GET /company/:company-id:/time-tracking/parameters

Example success response:

{
    "status": "success",
    "result": {
        "canUserManageProject": true
    }
}

class Response {
  status: string;
  result: Result;
}

class Result {
  canUserManageProject: boolean;
}

Time tracking module must be enabled and the user making the request must be company or module administrator.

Update time tracking parameters

PUT /company/:company-id:/time-tracking/parameters

{
  "canUserManageProject": false
}

class Request {
  canUserManageProject: boolean;
}

Example success response:

{
    "status": "success",
    "result": "Parameters updated successfully"
}

class Response {
  status: string;
  result: string;
}
Field name Type Required Comment
canUserManageProject boolean YES allowed values are True or False

Time tracking module must be enabled and the user making the request must be company or module administrator.

Projects

Create project

POST /company/:company-id:/time-tracking/projects

Request body

{
  "name": "Project name",
  "description": "Project description",
  "isBillable": false
}

class Request {
  name: string;
  description: string;
  isBillable: boolean;
}

Example success response:

{
    "status": "success",
    "result": {
        "id": "prj_QXpmOHdodmZ4TnRpS1o4ZldwYVBMZz09",
        "name": "Project name",
        "description": "Project description",
        "isBillable": false
    }
}

class Response {
  status: string;
  result: string;
}

Protected

Requires prior user login and user be part of the company with rights to manage projects within Time tracking

Field Type Required Validation Comment
name string Yes 2 - 100 characters project name
description string No 1 - 150 characters the desription of the project
isBillable boolean Yes TRUE/FALSE whether or not the project is billable

The endpoint is protected behind login and requires the appropriate user authorisation/access level

Update project

PUT /company/:company-id:/time-tracking/projects/:project-id

Request body

{
  "name": "Project updated name",
  "description": "Project updated description",
  "isBillable": true
}

class Request {
  name: string;
  description: string;
  isBillable: boolean;
}

Example success response:

{
    "status": "success",
    "result": "Project updated successfully"
}

class Response {
  status: string;
  result: string;
}

Protected

Requires prior user login and user be part of the company with rights to manage projects within Time tracking

Field Type Required Validation Comment
name string Yes 2 - 100 characters project name
description string No 1 - 150 characters the desription of the project
isBillable boolean Yes TRUE/FALSE whether or not the project is billable

The endpoint is protected behind login and requires the appropriate user authorisation/access level

Delete project

DELETE /company/:company-id:/time-tracking/projects/:project-id

Example success response:

{
    "status": "success",
    "result": "Project deleted successfully"
}

class Response {
  status: string;
  result: string;
}

Protected

Requires prior user login and user be part of the company with rights to manage projects within Time tracking

Get single project details

GET /company/:company-id:/time-tracking/projects/:project-id:

Example success response:

{
    "status": "success",
    "result": {
        "id": "prj_d1Z6RGYyVlRqaGRoeTNBMVJ3M2MxZz09",
        "name": "Project name",
        "description": "Project description",
        "isBillable": false
    }
}

class Response {
  status: string;
  result: Result;
}

Get company projects

GET /company/:company-id:/time-tracking/projects

Example success response:

{
    "status": "success",
    "result": [
        {
            "id": "prj_d1Z6RGYyVlRqaGRoeTNBMVJ3M2MxZz09",
            "name": "Project name",
            "description": "Project description",
            "isBillable": false
        },
        {
            "id": "prj_aGZGQXpzTkNvcUFSYk5QWXdTRjNMdz09",
            "name": "Project name 2",
            "description": "Project description 2",
            "isBillable": true
        }
    ]
}

class Response {
  status: string;
  result: Result;
}

Time entries

Add time entry

POST /company/:company-id:/time-tracking/users/:user-id:/time-entries

Request body

{
  "projectId": "prj_TTJsU2t6T3pQQks1endNbDRyRlhxUT09",
  "trackingDate": "2025-11-11",
  "startingTime": "08:30",
  "endingTime": "12:30",
  "note": "note",
  "isBreak": false,
  "isManual": true
}

class Request {
  projectId: string;
  trackingDate: date;
  startingTime: string;
  endingTime: string;
  note: string;
  isBreak: boolean;
  isManual: boolean
}

Example success response:

{
    "status": "success",
    "result": {
        "id": "ent_QXpmOHdodmZ4TnRpS1o4ZldwYVBMZz09",
        "userId": "usr_QXpmOHdodmZ4TnRpS1o4ZldwYVBMZz09",
        "trackingDate": "2025-11-11",
        "startingTime": "08:30",
        "endingTime": "12:30",
        "note": "note",
        "isBreak": false,
        "isManual": true,
        "project": {
            "id": "prj_TTJsU2t6T3pQQks1endNbDRyRlhxUT09",
            "name": "Test Project"
        }
    }
}

class Response {
  status: string;
  result: string;
}

Protected

Requires prior user login and user be part of the company with time tracking module being enabled

Field Type Required Validation Comment
projectId string No valid project id the id of an existing project
trackingDate date Yes YYYY-MM-DD the date the time entry is for
startingTime string Yes HH:MM when the time has started
endingTime string No HH:MM when the time has ended
note string No 0-500 characters a note for the specific entry
isBreak boolean yes TRUE/FALSE specifies if this is tracking time for a break
isManual boolean yes TRUE/FALSE specifies if this is a manual time entry

The endpoint is protected behind login and requires the time tracking module to be enabled and user be added to the company With this endpoint employees can track their time for both work and breaks. Also supports automatic and manual time tracking. Time can be tracked for specific projects, projects time tracking isn't mandatory part of the process

Update time entry

PUT /company/:company-id:/time-tracking/users/:user-id:/time-entries/:entry-id:

Request body

{
  "projectId": "prj_TTJsU2t6T3pQQks1endNbDRyRlhxUT09",
  "trackingDate": "2025-11-11",
  "startingTime": "08:40",
  "endingTime": "13:59",
  "note": "updated time entry note",
  "isBreak": false,
  "isManual": true
}

class Request {
  projectId: string;
  trackingDate: date;
  startingTime: string;
  endingTime: string;
  note: string;
  isBreak: boolean;
  isManual: boolean
}

Example success response:

{
    "status": "success",
    "result": "Time entry successfully updated"
}

class Response {
  status: string;
  result: string;
}

Protected

Requires prior user login and user be part of the company with time tracking module being enabled

Field Type Required Validation Comment
projectId string No valid project id the id of an existing project
trackingDate date Yes YYYY-MM-DD the date the time entry is for
startingTime string Yes HH:MM when the time has started
endingTime string No HH:MM when the time has ended
note string No 0-500 characters a note for the specific entry
isBreak boolean yes TRUE/FALSE specifies if this is tracking time for a break
isManual boolean yes TRUE/FALSE specifies if this is a manual time entry

Delete time entry

DELETE /company/:company-id:/time-tracking/projects/:entry-id:

Example success response:

{
    "status": "success",
    "result": "Time entry deleted successfully"
}

class Response {
  status: string;
  result: string;
}

Protected

Requires prior user login and user be part of the company with time tracking module being enabled

Get all user time entries

GET /company/:company-id:/time-tracking/users/:user-id:/time-entries?dateFrom=2024-11-10&dateTo=2024-11-22&projectId=:project-id:

Example success response:

{
    "status": "success",
    "result": [
        {
            "timeEntryId": "ent_d1Z6RGYyVlRqaGRoeTNBMVJ3M2MxZz09",
            "note": "note",
            "trackingDate": "2024-11-11",
            "startingTime": "13:30:00",
            "endingTime": "13:45:00",
            "isBreak": true,
            "isManual": true,
            "createdBy": "Jon Doe",
            "createdAt": "2025-10-22T11:04:26.000000Z",
            "updatedBy": "HR Omni Administrator",
            "hoursTracked": "00:15:00",
            "user": {
                "id": "usr_QXpmOHdodmZ4TnRpS1o4ZldwYVBMZz09",
                "firstName": "Jon",
                "lastName": "Doe",
                "email": "[email protected]"
            },
            "department": {
                "id": "dep_QXpmOHdodmZ4TnRpS1o4ZldwYVBMZz09",
                "name": "Dev-ops"
            },
            "project": {
                "id": "prj_d1Z6RGYyVlRqaGRoeTNBMVJ3M2MxZz09",
                "name": "Project name",
                "description": "Project description"
            }
        }
    ]
}

class Response {
  status: string;
  result: Result;
}

Get all time entries

GET /company/:company-id:/time-tracking/time-entries?projectId=:project-id:&dateFrom=2025-11-10&dateTo=2025-11-25

Example success response:

{
    "status": "success",
    "result": [
        {
            "timeEntryId": "ent_aGZGQXpzTkNvcUFSYk5QWXdTRjNMdz09",
            "note": "note",
            "trackingDate": "2025-11-11",
            "startingTime": "13:30:00",
            "endingTime": "13:45:00",
            "isBreak": true,
            "isManual": true,
            "createdBy": "Jon Doe",
            "createdAt": "2025-10-22T11:05:29.000000Z",
            "updatedBy": "HR Omni Administrator",
            "hoursTracked": "00:15:00",
            "user": {
                "id": "usr_QXpmOHdodmZ4TnRpS1o4ZldwYVBMZz09",
                "firstName": "Jon",
                "lastName": "Doe",
                "email": "[email protected]"
            },
            "department": {
                "id": "dep_QXpmOHdodmZ4TnRpS1o4ZldwYVBMZz09",
                "name": "Dev-ops"
            },
            "project": {
                "id": "prj_d1Z6RGYyVlRqaGRoeTNBMVJ3M2MxZz09",
                "name": "Project name",
                "description": "Project description"
            }
        }
    ]
}

class Response {
  status: string;
  result: Result;
}

User Invitations

Invite users

POST /company/:company-id:/users/invite

Request body

{
  "userEmails": [
    "[email protected]",
    "[email protected]",
    "[email protected]",
    "[email protected]",
    "[email protected]"
  ]
}

class Request {
  userEmails: string[];
}

Example success response:

{
  "status": "success",
  "result": {
    "invited": [
      "[email protected]",
      "[email protected]"
    ],
    "ignored": [
      {
        "email": "[email protected]",
        "reason": "Invitation already sent less than 30 minutes ago."
      },
      {
        "email": "[email protected]",
        "reason": "Already added to the company"
      },
      {
        "email": "[email protected]",
        "reason": "User blocked by System admin"
      }
    ]
  }
}

class Result {
  invited: string[];
  ignored?: IgnoreResult[];
}

class IgnoreResult {
  email: string;
  reason: string;
}

Protected

Requires prior user login.

Required fields

Field Type Validation Comment
userEmails array emails min:1 - max:20 records allowed in the list

Respond to invitation

POST /user/invitations/:inviteId:

Request body

{
  "action": "ACCEPT"
}

class Request {
  action: Action;
}

enum Action {
  ACCEPT, REJECT
}

Example success response:

{
  "status": "success",
  "result": "Invitation accepted!"
}

class Response {
  status: string;
  result: string;
}

Protected

Requires prior user login.

Required fields

Field Type Validation Comment
action enum ACCEPT, REJECT only one of the two allowed cases are allowed

User invitation list

GET /user/invitations?page=1&pageSize=12

Example success response:

{
  "status": "success",
  "result": {
    "totalRecords": 1,
    "totalPages": 1,
    "currentPage": 0,
    "currentPageSize": 20,
    "result": [
      {
        "id": "inv_a1ce8037d4c3dfd1d7d39b63835b8e",
        "companyName": "alex company",
        "sentBy": "John Doe",
        "expiresAt": "2023-02-22T11:02:40.000Z"
      }
    ]
  }
}

class Result {
  totalRecords: number;
  totalPages: number;
  currentPage: number;
  currentPageSize: number;
  result: Result[];
}
class Result {
  id: string;
  companyName: string;
  sentBy: string;
  expiresAt: date;
}

GET Parameters

parameter name type optional description
page int true this indicates the page number you request
pageSize int true the maximum records to be included in the page (default page size is 20)

Lists all user invitations. The endpoint is protected behind login and requires the appropriate user authorisation/access level.

User

Create user

POST /user/create

Request body

{
  "firstName": "Jossshny",
  "lastName": "Doe",
  "email": "[email protected]",
  "password": "test123456"
}

class Request {
  firstName: string;
  lastName: string;
  email: string;
  password: string;
}

Example success response:

{
  "status": "success",
  "result": "User created successfully"
}

class Response {
  status: string;
  result: string;
}
Field Type Validation Required
firstName string 1 - 60 characters YES
lastName string 1 - 60 characters YES
email string <= 128 caharcters YES
password string 10 - 100 characters YES

This endpoint will create new user in the system. The newly created user will not be to asspciated with any company, and they must validate their email address before they can login.

Verify user email

POST /user/verify/email

Request body

{
  "uuid": "cfm_e062508643bcae45751622d0d3d395"
}

class Request {
  uuid: string;
}

Example success response:

{
  "status": "success",
  "result": "User email verified successfully"
}

class Response {
  status: string;
  result: string;
}
Field Type Validation Comment
uuid string 30 - 34 characters email verification id

Each email verification id has a validity period, after this period lapses you re-send a new verification link and hit this endpoint with the new verification id.

User login

POST /user/login

Request body

{
  "email": "[email protected]",
  "password": "raw_user_password"
}

class Request {
  email: string;
  password: string;
}

Example success response:

{
  "status": "success",
  "result": "Success message here!"
}

class Response {
  status: string;
  result: string;
}
Field Type Validation Comment
email string <= 128 caharcters user email
password string 10 - 100 characters raw password as it was enetered by user

After a successfull user login a cookie will be set containing a JWT token. The cookie is httpOnly and secure which means that JavaScript won't be able to access it and it will only be sent over https protocol. Another cookie named isUserLoggedIn is also set that has httpOnly=false and can be used by JavaScript. This cookie holds same expiry value as the user session.

User details

GET /user/me

Example success response:

{
  "status": "success",
  "result": {
    "id": "************",
    "firstName": "John",
    "lastName": "Doe",
    "email": "[email protected]"
  }
}

class Response {
  status: string;
  result: User;
}

class User {
  id: string;
  firstName: string;
  lastName: string;
  email: string;
}

Use this endpoint when you have to retrieve the currently logged-in user details.

JSON response field Type Comment
id string user id value
firstname string user first name
lastName string user last name
email string user email

User update login details

PUT /user/login

Request body

{
  "email": "[email protected]",
  "password": "password_test",
  "newPassword": "password_test_new"
}

class Request {
  email?: string;
  password: string;
  newPassword?: string;
}

Example success response:

{
  "status": "success",
  "result": "Details updated successfully."
}

class Response {
  status: string;
  result: string;
}
Field Type Validation Comment
email string <= 128 caharcters user email
password string 10 - 100 characters raw password as it was enetered by user
newPassword string 10 - 100 characters raw password as it was enetered by user

User logout

GET /user/logout

Example success response:

{
  "status": "success",
  "result": "Success message here!"
}

Upon using this endpoint the current user session cookie will be unset.

Request password reset

POST /user/reset/password

Request body

{
  "email": "[email protected]"
}

class Request {
  email: string;
}

Example success response:

{
  "status": "success",
  "result": "Success message goes here"
}

class Response {
  status: string;
  result: string;
}
Field Type Validation Comment
email string <= 128 caharcters user email

This endpoint is unprotected and does not require user login to be called. User email is not validated for existence and called is most likely always going to receive a success response. If a user with provided email exists an email with password reset is going to be sent, otherwise no action is going to be performed.

Password reset

PUT /user/reset/password

Request body

{
  "uuid": "{password reset token}",
  "password": "raw_user_password",
  "repeatPassword": "raw_user_repeat_password"
}

class Request {
  uuid: string;
  password: string;
  repeatPassword: string;
}

Example success response:

{
  "status": "success",
  "result": "Success message goes here"
}

class Response {
  status: string;
  result: string;
}
Field Type Validation Comment
uuid string 30 - 34 characters password reset uuid token
password string 10 - 100 characters raw password as it was enetered by user
repeatPassword string 10 - 100 characters raw password as it was enetered by user

This endpoint is to be used in case user is being blocked due to too many unsuccessfull login attempts, or when user requests password reset themselves. In all cases an email will be sent to the user containing a URL to reset their password. The password reset URL will also contain the UUID needed to send this request.

User companies

GET /user/select/company?page=1&pageSize=20&search=company

Example success response:

{
  "status": "success",
  "result": {
    "search": "John",
    "totalRecords": 1,
    "totalPages": 1,
    "currentPage": 1,
    "currentPageSize": 20,
    "companies": [
      {
        "companyName": "*****",
        "companyId": "*****"
      }
    ]
  }
}

class Result {
  search?: string;
  totalRecords: number;
  totalPages: number;
  currentPage: number;
  currentPageSize: number;
  companies: Company[];
}

class Company {
  companyName: string;
  companyId: string;
}

GET Parameters

parameter name type optional description
page int true this indicates the page number you request
pageSize int true the maximum records to be included in the page (default page size is 20)
currentPage int true show the current page
currentPageSize int true show the record in the page
search string true show the search result

This endpoint returns the companies the user has access to (may be more than one result). The endpoint requires the user to be logged in.

Billing

GET /company/:company-id:/billing/settings

Example success response:

{
  "status": "success",
  "result": "billing_session_url"
}

class Result {
  status: string;
  result: string;
}

Description

The user must be company administrator and logged in. This endpoint will create a session url that the user can visit to set/update their payment methods on Stripe

Get payment methods

GET /company/:company-id:/billing/payment-methods

Example success response:

{
  "status": "success",
  "result": {
    "cards": [
      {
        "brand": "mastercard",
        "exp_month": 11,
        "exp_year": 2024,
        "last4": "4444"
      },
      {
        "brand": "visa",
        "exp_month": 11,
        "exp_year": 2024,
        "last4": "4242"
      }
    ]
  }
}

class Result {
    status: string;
    result: Result[];
}

class Result {
    cards: Cards[];
}

class Cards {
    brand: string;
    exp_month: number;
    exp_year: number;
    last4: string;
}

Description

To access this endpoint the user must be logged-in and have at least company admin read rights. Endpoint provides all payment methods for a given company

Country

Country list

GET /countries

Example success response:

{
  "status": "success",
  "result": [
    {
      "id": 1,
      "iso": "IE",
      "nicename": "Irealnd"
    },
    {
      "id": 2,
      "iso": "GB",
      "nicename": "United Kindom"
    }
  ]
}

class Result {
  status: string;
  result: Country[];
}

class Country {
  id: number;
  iso: string;
  nicename: string;
}

GET Parameters

parameter name type optional description
showAll bool true this indicates if entire list of available countries needs to be returned, or just the active/allowed countries. Default value is false

This endpoint provides currently supported country locations by the platform. It should be used in a dropdown list on the registration form for user to pick from. The id of a country is to be send with the registration request to indicate the location of the company that is registering on the plaform. Additional showAll get parameter is allowed in case the entire list of countries needs to be used in places within the application, for example when nationality of a user needs to be set we can use this list to suggest country names in a dynamic search field.

CSRF

Get Token

GET /

Cross-Site Request Forgery (CSRF)

Almost all of the API endpoints are protected for CSRF and a request header X-Csrf-Token must be set with each request containing the value of a cookie named token. Token cookie can be retrieved when visiting CSRF token endpoint

If you encounter an error that looks like {"status":"error","code":4005,"message":"Token not set"} It means that you need to get a token cookie and set the X-Csrf-Token in order to make a successfull request.

Respectively if you encounter an error like {"status":"error","code":4006,"message":"Invalid token provided"} it means that the value of the request header X-Csrf-Token does not match the value of the token cookie.

Once a request is made a cookie with name token will be set and its value must be send back whenever X-Csrf-Token value is required.

Errors

HTTP status

Example error response

{
    "status": "error",
    "code": 4001,
    "message": "Bad Request"
}

class ErrorResult {
  status: string;
  code: number;
  message: string;
}

The HR Omni API uses the following HTTP status codes:

Error Code Meaning
400 Bad Request -- Your request is invalid.
401 Unauthorized -- Your API key is wrong.
403 Forbidden -- The record requested is hidden for administrators only.
404 Not Found -- The specified record could not be found.
405 Method Not Allowed -- You tried to access a kitten with an invalid method.
406 Not Acceptable -- You requested a format that isn't json.
410 Gone -- The resource requested has been removed.
500 Internal Server Error -- We had a problem with the server. Try again later.
503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.

Internal codes

This codes are included in the error response JSON.

Error Code Description Recovery
3001 Validation error (request data can not be validated and is rejected) Fix the request JSON or look in the error message for more details
4001 Not found (no record with requested ID is found in the database) Provide valid record ID when making the request
4002 Forbidden action (User is missing permissions to perform this action) Unable to recover from this error
4003 Invalid action (The action can not be executed) User is trying to perform invalid action. Reason for this can be approving expired invitation etc.
4004 Missing session cookie User must login to be able to proceed
4005 Missing CSRF token Either X-Csrf-Token header, token cookie or both are missing. Check your request for this
4006 Invalid CSRF token value Valus in X-Csrf-Token header and token cookie are not equal and validation failed
4007 Business logic disallowed The action performed is stopped by the business logic. Unable to recover from this error
4008 Unable to send email This error is thrown when there is an issue sending emails. Unable to recover from this error
5000 Unexpected error Unexpected error was received while executing the request. Unable to recover from this error
5001 Database error There is a database error while executing the request. Unable to recover from this error
JSON TypeScript