NAV Navbar

Introduction

The HeavenHR public REST API for accessing and storing employee and company data

Last Updated: 2020-11-30
Customers can access a number of publicly exposed HeavenHR endpoints to facilitate data sharing and synchronization needs.

Contact information:
publicapi@heavenhr.de

Access Control

# example nodeJS code to generate api key from client id and client secret

var CryptoJS = require("crypto-js");

var client_id = ("heavenHr_clientId");
var client_secret = ("heavenHr_clientSecret");
var rawStr = client_id + ":" + client_secret;
var utf8Str = CryptoJS.enc.Utf8.parse(rawStr);
var heavenHrApiKey = CryptoJS.enc.Base64.stringify(utf8Str);

console.log('encrypted:', heavenHrApiKey);

# Before your application can access private data using a HeavenHR API, 
# it must obtain an access token that grants access to that API.
curl "https://api.heavenhr.com/api/v2/oauth2/token?grant_type=client_credentials&scope=all"
  -X GET -H "Authorization: Basic heaven_hr_api_key"
  1. Obtain OAuth 2.0 credentials for the company. Contact the customer care for getting your client id and client secret

  2. Generate the api key using client id and client secret. Obtain an access token using api key.

  3. Access token need to be passed to all the subsequent API calls.

  4. Refresh the access token, if necessary

HeavenHR expects for the authorization key to be included in all API requests to the server in a header that looks like the following:

Information

Health Check

To verify the status of the API, verify the following returns a 200 response.

curl 'https://api.heavenhr.com/api/v2/health/check' 

> Returns the following for a healthy response:

{
  "message": "OK"
}

Employees

Create a new employee

curl 'https://api.heavenhr.com/api/v2/employees/ -X POST ' 

> The above command returns JSON structured like this:

{
    "startDate": "2017-04-13",
    "endOfContract": "2022-04-13",
    "professionalEmail": "professionalEmail@heavenhr.de",
    "jobTitle": "Head of Sales",
    "permanentOrTemporary": "PERMANENT",
    "streetPersonal": "Griefwalderstrasse",
    "streetNumberPersonal": 219,
    "additionalContractInformation": "The employee has the right to take leave 24 days a year.",
    "locationId": "_bE1Zi2WRANH76y0vDbdEdA_",
    "employeeNumber": 716,
    "gender": "MALE",
    "nationality": "DE",
    "occupation": "Manager",
    "firstName": "Max",
    "fullTimeOrPartTime": "FULL_TIME",
    "employmentType": "FREELANCER",
    "lastName": "Musterman",
    "jobStatus": "CREATED_EXISTING",
    "mobileWork": 63121,
    "dateOfBirth": "1984-07-17",
    "departmentId": "_EaH3L12VPSVhuSDPqkKIdg_",
    "phonePersonal": 4921348182,
    "costCenterId": "_3q4nkYvIocIJDUhyZJh5dQ_",
    "email": "email@heavenhr.de",
    "sendOnboardingEmail": true,
    "customAttributes": [
       {
        "id": "_Aeqew@adq3dsfADRaqw",
        "name": "Customer attribute Name",
        "value": "I am superman"
       }
    ],
    "contract": {
        "grossSalary": 80000,
        "settlementPeriodSalary": "perYear",
        "holidaysPerYear": 24,
        "workingHoursPerWeek": 40,
        "probationPeriod": "6Months",
        "noticePeriodDuringProbation": "4Weeks",
        "noticePeriodDuringProbationStart": "endOfWeek"
    },
    "workSchedule": {
        "scheduledDate": "2017-04-15",
        "days": [
            {
                "dayOfWeek": "MONDAY",
                "worktimeInMinutes": 380
            },
            {
                "dayOfWeek": "FRIDAY",
                "worktimeInMinutes": 360
            }
        ],
        "defaultSchedule": "TRUE"
    }
}

POST /employees/

Description: Add an employee to your company, and send an email for the employee to register with HeavenHR.

Parameters

Name Description Required Schema
body Employee to be added to the company Yes EmployeeCreatedRequest

Responses

Code Description Schema
201 The submitted employee has been created CreateEmployeeResponse
400 The submitted employee record is invalid CreateEmployeeResponse
403 Invalid permissions. The key you are using is incorrect, or only has read access granted

Get a employee

curl 'https://api.heavenhr.com/api/v2/employees/{employee_id}' 

> The above command returns JSON structured like this:
{
    "startDate": "2017-04-13",
    "endOfContract": "2022-04-13",
    "professionalEmail": "professionalEmail@heavenhr.de",
    "jobTitle": "Head of Sales",
    "permanentOrTemporary": "PERMANENT",
    "streetPersonal": "Griefwalderstrasse",
    "streetNumberPersonal": 219,
    "additionalContractInformation": "The employee has the right to take leave 24 days a year.",
    "locationId": "_bE1Zi2WRANH76y0vDbdEdA_",
    "employeeNumber": 716,
    "gender": "MALE",
    "nationality": "DE",
    "occupation": "Manager",
    "firstName": "Max",
    "fullTimeOrPartTime": "FULL_TIME",
    "employmentType": "FREELANCER",
    "lastName": "Musterman",
    "jobStatus": "CREATED_EXISTING",
    "mobileWork": 63121,
    "dateOfBirth": "1984-07-17",
    "departmentId": "_EaH3L12VPSVhuSDPqkKIdg_",
    "phonePersonal": 4921348182,
    "costCenterId": "_3q4nkYvIocIJDUhyZJh5dQ_",
    "email": "email@heavenhr.de",
    "sendOnboardingEmail": true,
    "customAttributes": [
       {
        "id": "_Aeqew@adq3dsfADRaqw",
        "name": "Customer attribute Name",
        "value": "I am superman"
       }
    ],
    "contract": {
        "grossSalary": 80000,
        "settlementPeriodSalary": "perYear",
        "holidaysPerYear": 24,
        "workingHoursPerWeek": 40,
        "probationPeriod": "6Months",
        "noticePeriodDuringProbation": "4Weeks",
        "noticePeriodDuringProbationStart": "endOfWeek"
    },
    "workSchedule": {
        "scheduledDate": "2017-04-15",
        "days": [
            {
                "dayOfWeek": "MONDAY",
                "worktimeInMinutes": 480
            },
            {
                "dayOfWeek": "FRIDAY",
                "worktimeInMinutes": 360
            }
        ],
        "defaultSchedule": "TRUE"
    }
}

Description: Find employee by ID and return all the employee details

GET /employees/{id}

Parameters

Name Description Required Schema
id The ID of employee to return Yes string

Responses

Code Description Schema
200 Success Employee
400 Invalid ID supplied
404 Employee not found

Update a employee

curl 'https://api.heavenhr.com/api/v2/employees/{employee_id} -X PATCH' 

> The above command returns JSON structured like this:

{
    "startDate": "2017-04-13",
    "endOfContract": "2022-04-13",
    "professionalEmail": "professionalEmail@heavenhr.de",
    "jobTitle": "Head of Sales",
    "permanentOrTemporary": "PERMANENT",
    "streetPersonal": "Griefwalderstrasse",
    "streetNumberPersonal": 219,
    "additionalContractInformation": "The employee has the right to take leave 24 days a year.",
    "locationId": "_bE1Zi2WRANH76y0vDbdEdA_",
    "employeeNumber": 716,
    "gender": "MALE",
    "nationality": "DE",
    "occupation": "Manager",
    "firstName": "Max",
    "fullTimeOrPartTime": "FULL_TIME",
    "employmentType": "FREELANCER",
    "lastName": "Musterman",
    "jobStatus": "CREATED_EXISTING",
    "mobileWork": 63121,
    "dateOfBirth": "1984-07-17",
    "departmentId": "_EaH3L12VPSVhuSDPqkKIdg_",
    "phonePersonal": 4921348182,
    "costCenterId": "_3q4nkYvIocIJDUhyZJh5dQ_",
    "email": "email@heavenhr.de",
    "sendOnboardingEmail": true,
    "customAttributes": [
       {
        "id": "_Aeqew@adq3dsfADRaqw",
        "name": "Customer attribute Name",
        "value": "I am superman"
       }
    ],
    "contract": {
        "grossSalary": 80000,
        "settlementPeriodSalary": "perYear",
        "holidaysPerYear": 24,
        "workingHoursPerWeek": 40,
        "probationPeriod": "6Months",
        "noticePeriodDuringProbation": "4Weeks",
        "noticePeriodDuringProbationStart": "endOfWeek"
    },
    "workSchedule": {
        "scheduledDate": "2017-04-15",
        "days": [
            {
                "dayOfWeek": "MONDAY",
                "worktimeInMinutes": 480
            },
            {
                "dayOfWeek": "FRIDAY",
                "worktimeInMinutes": 360
            }
        ],
        "defaultSchedule": "TRUE"
    }
}

PATCH /employees/{id}

Description: Update the details of a specific employee. This will only update the fields that are sent, including fields for Contract and WorkSchedule

Parameters

Name Description Required Schema
id The ID of employee to update Yes string

Responses

Code Description Schema
204 Success EmployeeUpdate
400 Invalid ID supplied
404 Employee not found

Get all employees

curl 'https://api.heavenhr.com/api/v2/employees/ -X GET' 

> The above command returns JSON structured like this:

{
    "page": 0,
    "pageSize": 200,
    "totalItems": 23,
    "totalPages": 1,
    "data": [
        {
            "id": "_CNr_06hxMX3DXdrkbY4FQw_",
            "firstName": "aaaaa First Name",
            "lastName": "aaaaa last Name",
            "employeeNumber": 1,
            "jobStatus": "CREATED_EXISTING",
            "updatedAt": "2018-09-25T12:17:26.522",
            "departmentName": "IT",
            "departmentId": null,
            "email": "nonexisting@aadas.com"
        },
        {
            "id": "_QU3zYEuk2WPclWSMv7vJQw_",
            "firstName": "bbbb First Name",
            "lastName": "last Name",
            "employeeNumber": 3,
            "jobStatus": "HIRED",
            "updatedAt": "2018-09-25T12:18:17.059",
            "departmentName": "Sales",
            "departmentId": null,
            "email": "donotreply@aadas.com"
        }
     ]
}

Find all employees in a sorted, paginated list by zero or more of the specified filters and return with limited fields

GET /employees

Description: Returns a list of employees with limited fields

Parameters

Name Description Required Schema
page The current page number. Zero-indexed, so the first page is 0 No integer
pageSize How many items are in each page No integer
employeeNumber Returns the employee with this employee number No string
departmentId Returns all employees with this department id No string
jobStatus The status of employee No string
startDate Returns all employees with this start date No dateTime
updatedAt Returns all employees that have been updated since this time No dateTime in format of ISO DateTime Format: yyyy-MM-dd’T’HH:mm:ss.SSSZ, e.g. “2000-10-31T01:30:00.000-05:00”.

Responses

Code Description Schema
200 Success PagedEmployeeResponse
404 No employees found (for this page)

Create Absence budget for an Employee

curl 'https://api.heavenhr.com/api/v2/employees/{id}/absencebudgets -X POST' -d '{"year":2018}'

Description: Create the budget for absence for a particular employee

Parameters

Name Description Required Schema
id The ID of employee to update Yes string

Create time tracking Request

curl 'https://api.heavenhr.com/api/v2/employees/{id}/timetracking -X POST ' 

{
  "projectId" : "_3PSTCjfM7B2qg5Az6wuRVg_",
  "startDate": "2019-10-24",
  "endDate": "2019-10-24",
  "startTime": "09:50", 
  "endTime": "18:55",
  "total" : "",
  "breakTime" : "30",
  "comment" : "",
  "status" : "REQUESTED",
  "categories": [
      "_xelst4ASGYOfEf30Qr_bMQ_",
      "_bJunkaJUb68E-Yn7y5ya6Q_"
    ]
}

POST /employees/{id}/timetracking

Description: Add new time tracking request to an Employee. the allowed status while creation are EDITABLE, REQUESTED.

Parameters

Name Description Required Schema
body Time Tracking Request for Employee Yes TimeTrackingCreateRequest

Responses

Code Description Schema
201 The submitted Time tracking request has been created TimeTrackingCreateResponse
400 The submitted Time tracking request is invalid
403 Invalid permissions. The key you are using is incorrect, or only has read access granted

Update time Tracking Request

curl 'https://api.heavenhr.com/api/v2/employees/{employee_id}/timetracking/{id} -X PATCH' 

{
  "projectId" : "_3PSTCjfM7B2qg5Az6wuRVg_",
  "startDate": "2019-10-24",
  "endDate": "2019-10-24",
  "startTime": "08:00",
  "endTime": "17:30",
  "total": 510,
  "breakTime" : 30,
  "comment" : "Time tracking request #1",
  "categories": [
      "_xelst4ASGYOfEf30Qr_bMQ_"
    ]
}

PATCH employees/{employee_id}/timetracking/{id}

Description: Update the details of a specific time Tracking Request. This will only update the fields that are sent,

Parameters

Name Description Required Schema
employee_id The owner employee Id of the time tracking request. Yes string
id the ID of the time Tracking request to be updated. Yes string
status the target time tracking status Yes TimeTrackingStatus

Responses

Code Description Schema
200 Success
400 Invalid ID supplied
404 Employee not found

Update the status of time Tracking Request

curl 'https://api.heavenhr.com/api/v2/employees/{employee_id}/timetracking/{id}/{status} -X PATCH' 

PATCH employees/{employee_id}/timetracking/{id}/{status}

Description: Update the status of the request to one of the following values: REQUESTED, APPROVED, REJECTED.

Parameters

Name Description Required Schema
employee_id The owner employee Id of the time tracking request. Yes string
id the ID of the time Tracking request to be updated. Yes string
status the target time tracking status Yes TimeTrackingStatus

Responses

Code Description Schema
200 Success
400 Invalid ID supplied
404 Employee or time tracking request not found

Get Time tracking request

curl 'https://api.heavenhr.com/api/v2/employees/{employee_id}/timetracking/{id}' 

> The above command returns JSON structured like this:
{
  "projectId" : "_3PSTCjfM7B2qg5Az6wuRVg_",
  "requestDate":"2019-10-24",
  "status" : "REQUESTED",
  "startTime":"09:50",  
  "endTime":    "18:55",
  "totalTimeInMinutes" :    "",
  "breakTimeInMinutes" : "30",
  "comment" : "",
  "categories": [
    "_xelst4ASGYOfEf30Qr_bMQ_",
    "_bJunkaJUb68E-Yn7y5ya6Q_"
  ]
}

Description: Get time tracking request for employee by ID.

GET /employees/{employee_id}/timetracking/{id}

Parameters

Name Description Required Schema
employee_id The owner employee Id of the time tracking request. Yes string
id the id of the requested time Tracking Yes string

Responses

Code Description Schema
200 Success TimeTracking
404 Employee not found or Request Id Not Found

Get employees' time tracking requests

curl 'https://api.heavenhr.com/api/v2/employees/{employee_id}/timetracking -X GET' 

> The above command returns JSON structured like this:

{
    "links": [],
    "data": [
        {
            "id": "_vnU2kfgMtfJlNApQm0uZdw_",
            "employeeId": "_3PSTCjfM7B2qg5Az6wuRVg_",
            "projectId": null,
            "requestDate": "2019-09-25",
            "startTime": "09:50",
            "endTime": "24:00",
            "totalTimeInMinutes": 790,
            "breakTimeInMinutes": 60,
            "comment": "",
            "status": "APPROVED",
            "categories": [
                {
                    "id": "_xelst4ASGYOfEf30Qr_bMQ_",
                    "name": "new category",
                    "status": "ACTIVE"
                }
            ]
        }
    ],
    "meta": {
        "page": 0,
        "pageSize": 1,
        "count": 1
    }
}

Find all employees's time tracking requests in a sorted, paginated list by zero or more of the specified filters

GET /employees/{employee_id}/timetracking

Description: Returns a list of employees' time tracking requests with limited fields

Parameters

Name Description Required Schema
page The current page number. Zero-indexed, so the first page is 0 No integer
pageSize How many items are in each page No integer
status the time tracking request status to filter with No string
requestDate the time tracking request start date to filter with No string

Responses

Code Description Schema
200 Success PagedTimeTrackingRequest
404 No time tracking requests found for the given employee Id

Get Time tracking projects

curl 'https://api.heavenhr.com/api/v2/employees/{employee_id}/timetracking/projects' 

> The above command returns JSON structured like this:
{
    "id": "_t22XLGQkdeRvWb1JK_RTMA_",
    "name": "testing ",
    "status": "ACTIVE"
}

Description: Get time tracking request for employee.

GET /employees/{employee_id}/timetracking/projects

Parameters

Name Description Required Schema
employee_id The employee Id to list the projects for. Yes string

Responses

Code Description Schema
200 Success Project List
404 Employee not found

Get all shifts for an employee

curl 'https://api.heavenhr.com/api/v2/employees/{employee_id}/shifts' -X GET 

> The above command returns JSON structured like this:
{
    "page": 0,
    "pageSize": 200,
    "totalItems": 2,
    "totalPages": 1,
    "data": [
       {
          "id": "_XjAmqPKx5SdmM-KlbHQTQA_",
          "startTime": "2019-01-02T08:00:00",
          "endTime": "2019-01-02T17:00:00",
          "status": "PUBLISHED"
       },
       {
          "id": "_XjAmqPKx5SdmM-KlbHQTQA_",
          "startTime": "2019-01-03T08:00:00",
          "endTime": "2019-01-03T17:00:00",
          "status": "DRAFT"
       }
    ]
}

Description: Get all shifts for an employee

GET /employees/{employee_id}/shifts/

Parameters

Name Description Required Schema
employee_id The employee Id to get all shifts Yes string
startDate Start date for search Yes ISO Date Format: yyyy-MM-dd
endDate End date for search Yes ISO Date Format: yyyy-MM-dd

Responses

Code Description Schema
200 Success PagedShiftResponse
404 Employee not found

Company Information

Get Company info

curl 'https://api.heavenhr.com/api/v2/company/ -X GET' 

{
    "links": [],
    "data": [
        {
            "id": "_XjAmqPKx5SdmM-KlbHQTQA_",
            "name": "Awesome HR company",
            "customAttributes": [
                {
                    "id": "_9X8jV4qypU6As7SlyBtT8w_",
                    "name": "test attribute",
                    "type": "STRING",
                    "category": "PERSON_BASIC_DATA"
                }
            ]
        }
    ]
}

Description: Returns the company info. This API also returns the custom Attributes defined. The ID of the customAttributes is used for creating/updating the employees with the value.

Parameters

Responses

Code Description Schema
200 Success CompanyResponse

Get Organizations

curl 'https://api.heavenhr.com/api/v2/company/organizations -X GET' 

> The above command returns JSON structured like this:

{
  "data": [
    {
      "headsOfUnit": null,
      "pathName": "HeavenHR",
      "children": [
        null
      ],
      "name": "HeavenHR",
      "id": "_WBMlOvhvkQ-7ABKJ9aK4Nw_"
    }
  ],
}   ]
}

Traverse the hierarchical structure of a company Get /company/organizations

Description: Returns the company structure tree

Responses

Code Description Schema
200 Success PagedOrganizationResponse
404 No company organization structure information found (for this page)

Get locations

curl 'https://api.heavenhr.com/api/v2/company/locations -X GET' 

> The above command returns JSON structured like this:

{
  "totalItems": 1,
  "totalPages": 1,
  "data": [
    {
      "city": "Berlin",
      "id": "_WBMlOvhvkQ-7ABKJ9aK4Nw_",
      "name": "Berlin Office",
      "country": "Germany"
    }
  ],
  "page": 0,
  "pageSize": 0
}

Find all locations for a company

GET /company/locations

Description: Returns a list of locations

Parameters

Name Located in Description Required Schema
page The current page number. Zero-indexed, so the first page is 0 No integer
pageSize How many items are in each page No integer

Responses

Code Description Schema
200 Success PagedLocationResponse
404 No location information found (for this page)

Get costcenters

curl 'https://api.heavenhr.com/api/v2/company/cost-centers -X GET' 

> The above command returns JSON structured like this:

{
    "page": 0,
    "pageSize": 200,
    "totalItems": 2,
    "totalPages": 1,
    "data": [
        {
            "id": "_Lg9ISEggCDLw9Lj6motG1Q_",
            "number": "1485",
            "name": "Marketing",
            "employeeCount": 5
        },
        {
            "id": "_84_UGt4Ljku6i7Ka15XO1Q_",
            "number": "1359",
            "name": "Sales",
            "employeeCount": 7
        }
    ]
}

Find all the cost centers for a company

GET /company/cost-centers

Description: Returns a list of cost centers

Parameters

Name Located in Description Required Schema
page The current page number. Zero-indexed, so the first page is 0 No integer
pageSize How many items are in each page No integer

Responses

Code Description Schema
200 successful operation PagedCostCenterResponse
404 No cost center information found (for this page)

Get detailed shift

curl 'https://api.heavenhr.com/api/v2/company/shifts/{shift_id}' -X GET 

> The above command returns JSON structured like this:
{
  "id": "_XjAmqPKx5SdmM-KlbHQTQA_",
  "breakInMinutes": 60, 
  "totalInMinutes": 480,
  "type": {
     "id": "_5Q8jY0qypU3Fs7PlyUtJ3w_",
     "name": "Day Shift",
     "status": "ACTIVE"
  },
  "startTime": "2019-01-02T08:00:00",
  "endTime": "2019-01-02T17:00:00",
  "assignedUsers": [
     "_xQfoTYosQrl3WKzjFg431A_",
     "_7qPbfSo-b_0HMtPK7o7wdg_"
  ],
  "status": "PUBLISHED",
  "orgaUnits": [
    "_bE1Zi2WRANH76y0vDbdEdA_"
  ],
  "occupations": [ 
    {
      "name": "Hoster",
      "count": 3
    } 
  ],
  "shortHanded": false 
}

Description: Get detailed shift

GET /company/shifts/{shift_id}

Parameters

Name Description Required Schema
shift_id The shift Id desired. Yes string

Responses

Code Description Schema
200 Success ShiftDetail
404 Shift not found

Get shifts

curl 'https://api.heavenhr.com/api/v2/company/shifts' -X GET 

> The above command returns JSON structured like this:
{
    "page": 0,
    "pageSize": 200,
    "totalItems": 2,
    "totalPages": 1,
    "data": [
       {
          "id": "_XjAmqPKx5SdmM-KlbHQTQA_",
          "startTime": "2019-01-02T08:00:00",
          "endTime": "2019-01-02T17:00:00",
          "assignedUsers": [
            "_xQfoTYosQrl3WKzjFg431A_",
            "_7qPbfSo-b_0HMtPK7o7wdg_"
          ],
          "status": "PUBLISHED"
       },
       {
          "id": "_XjAmqPKx5SdmM-KlbHQTQA_",
          "startTime": "2019-01-03T08:00:00",
          "endTime": "2019-01-03T17:00:00",
          "assignedUsers": [
            "_xQfoTYosQrl3WKzjFg431A_",
            "_7qPbfSo-b_0HMtPK7o7wdg_",
            "_IV8VZcWICnD_NV4aFJuZig_"
          ],
          "status": "DRAFT"
       }
    ]
}

Description: Returns a list of shifts

GET /company/shifts/

Parameters

Name Description Required Schema
startDate Start date for search Yes ISO Date Format: yyyy-MM-dd
endDate End date for search Yes ISO Date Format: yyyy-MM-dd
status The status of the shift. Default value is PUBLISHED No string Values: DRAFT or PUBLISHED

Responses

Code Description Schema
200 Success PagedShiftCompanyResponse
403 Invalid permissions. The key you are using is incorrect, or only has read access granted

Get categories

curl 'https://api.heavenhr.com/api/v2/company/timetracking/categories' -X GET 

> The above command returns JSON structured like this:
{
    "page": 0,
    "pageSize": 200,
    "totalItems": 2,
    "totalPages": 1,
    "data": [
        {
            "id": "_xelst4ASGYOfEf30Qr_bMQ_",
            "name": "new category",
            "status": "ACTIVE"
        },
        {
            "id": "_bJunkaJUb68E-Yn7y5ya6Q_",
            "name": "neu Kategorie",
            "status": "ACTIVE"
        }
    ]
}

Description: Returns a list of categories for time tracking

GET company/timetracking/categories

Parameters

Name Located in Description Required Schema
page The current page number. Zero-indexed, so the first page is 0 No integer
pageSize How many items are in each page No integer

Responses

Code Description Schema
200 Success PagedCategoriesResponse
403 Invalid permissions. The key you are using is incorrect, or only has read access granted

Payroll

Get Company Payroll Periods

curl 'https://api.heavenhr.com/api/v2/payroll/payrollperiod -X GET' 

> The above command returns JSON structured like this:

{
    "page": 0,
    "pageSize": 1000,
    "totalItems": 2,
    "totalPages": 1,
    "data": [
        {
            "id": "_WBMlOvhvkQ-7ABKJ9aK4Nw_",
            "dateStart": "2018-04-01",
            "dateEnd": "2018-04-30",
            "status": "OPEN"
        },
        {
            "id": "_fGoS4__ElNagsberYKfYJQ_",
            "dateStart": "2018-03-01",
            "dateEnd": "2018-03-31",
            "status": "CLOSED"
        }
    ]
}

GET /payroll/payrollperiod

Description: Get all the payroll periods for a company, the current and the closed

Parameters

Name Description Required Schema
page The current page number. Zero-indexed, so the first page is 0 No integer
pageSize How many items are in each page No integer

Responses

Code Description Schema
200 Successful operation PagedPayrollPeriodResponse
403 Invalid permissions. The key you are using is incorrect, or do not have permissions for that operation

Get Sub Company Payroll Periods

curl 'https://api.heavenhr.com/api/v2/payroll/{subcompany_id}/payrollperiod -X GET' 

> The above command returns JSON structured like this:

{
    "page": 0,
    "pageSize": 1000,
    "totalItems": 2,
    "totalPages": 1,
    "data": [
        {
            "id": "_fGoS4__ElNniBaWsEKfYJQ_",
            "dateStart": "2018-04-01",
            "dateEnd": "2018-04-30",
            "status": "OPEN"
        },
        {
            "id": "_9X8jV4qypU6As7SlyBtT8w_",
            "dateStart": "2018-03-01",
            "dateEnd": "2018-03-31",
            "status": "CLOSED"
        }
    ]
}

GET /payroll/{subcompany_id}/payrollperiod

Description: Get all the payroll periods for a sub company, the current and the closed

Parameters

Name Description Required Schema
subcompany_id The ID of the sub company Yes string
page The current page number. Zero-indexed, so the first page is 0 No integer
pageSize How many items are in each page No integer

Responses

Code Description Schema
200 Successful operation PagedPayrollPeriodResponse
403 Invalid permissions. The key you are using is incorrect, or do not have permissions for that operation

Get Payroll Period Salary Details

curl 'https://api.heavenhr.com/api/v2/payroll/payrollperiod/{payrolperiod_id}/salary -X GET' 

> The above command returns JSON structured like this:

{
    "page": 0,
    "pageSize": 1000,
    "totalItems": 2,
    "totalPages": 1,
    "data": [
        {
            "employeeId": "_dK4xhpkYvXCjlMcmppVRdg_",
            "firstName": "Max",
            "lastName": "Musterman",
            "personelNumber": "1001",
            "salary": {
                "fixedSalary": 1500000000,
                "others": 301
            }
        },
        {
            "employeeId": "_rT6xhpkPvYBjlZcrhgQAfw_",
            "firstName": "Fernanda",
            "lastName": "Fructuoso",
            "personelNumber": "1002",
            "salary": {
                 "fixedSalary": 1600000000,
                 "others": 400
            }
        }
    ]
}

GET /payroll/payrollperiod/{payrollperiod_id}/salary

Description: Get all the salary details for a payroll period

Parameters

Name Description Required Schema
payrolperiod_id The ID of the payroll period Yes string
page The current page number. Zero-indexed, so the first page is 0 No integer
pageSize How many items are in each page No integer

Responses

Code Description Schema
200 Successful operation PagedPayrollPeriodSalaryDetailsresponse
403 Invalid permissions. The key you are using is incorrect, or do not have permissions for that operation
404 No payroll period found for the given ID

Recruiting

Get Vacancy

curl 'https://api.heavenhr.com/api/v1/positions/public/vacancies/{vacancy_id} -X GET' 

> The above command returns JSON structured like this:

{
    "data": [
        {
            "id": "_c4mWzU4vUb_U6PV0yxQl_g_",
            "jobTitle": "Head of Sales",
            "description": "<p>Position to be the Head of our sales department.</p>",
            "employmentTypes": [
                "FULL_TIME"
            ],
            "numberOfOpenings": 1,
            "location": "Brussles",
            "department": "Sales",
            "publicationDate": "2019-02-11",
            "numberOfApplicants": 0,
            "companyId": "_Jn4W-x3rvGß0Rk-CwYUYYA_",
            "status": "PUBLISHED",
            "industry": "TELECOMMUNICATIONS",
            "fieldOfWork": "SERVICE",
            "positionType": "MANAGER",
            "seniority": "SENIOR",
            "employmentStartDate": "2019-06-11",
            "hiringOrganization": "Company Z4",
            "qualifications": "<p>Masters Degrees in Sales Management</p>",
            "responsibilities": "<p>Entire department<p>",
            "incentives": "<p>Bus ticket<p>",
            "contact": "contact info goes here"
        }
    ]
}

GET /positions/public/vacancies/{vacancy_id}

Description: Find vacancy by ID and return all the vacancy details

Parameters

Name Description Required Schema
vacancy_id The ID of the vacancy Yes string

Responses

Code Description Schema
200 Successful operation PublicVacancy
403 Invalid permissions. The key you are using is incorrect, or do not have permissions for that operation
404 No vacancy found for the given ID

Get All Vacancies

curl 'https://api.heavenhr.com/api/v1/positions/public/vacancies/ -X GET' 

> The above command returns JSON structured like this:
{
    "data": [
        {
            "id": "_rW4JzrNQIs8LuqHXliwlaA_",
            "email": "new@email.com",
            "jobTitle": "Full-stack web developer",
            "employmentTypes": [
                "FULL_TIME"
            ],
            "location": "Paris",
            "department": "IT",
            "publicationDate": "2019-01-03",
            "status": "PUBLISHED",
            "industry": "PRINT MEDIA",
            "fieldOfWork": "SERVICE",
            "positionType": "FULL-TIME",
            "seniority": "MANAGER",
            "employmentStartDate": "2019-07-01",
            "hiringOrganization": "<p>Company X</p>",
            "qualifications": "<p>Java 8</p>",
            "responsibilities": "<p>Code, test, deploy</p>",
            "incentives": "<p>free coffee</p>",
            "contact": "contact information goes here"
        },
        {
            "id": "_S2fzaC9XFKXrqy9adYBLGg_",
            "email": "new@email.com",
            "jobTitle": "Sales Manager",
            "employmentTypes": [
                "FULL_TIME"
            ],
            "location": "Brussles",
            "department": "Marketing and Sales",
            "publicationDate": "2019-03-11",
            "status": "PUBLISHED",
            "industry": "TELECOMMUNICATIONS",
            "fieldOfWork": "SERVICE",
            "positionType": "MANAGER",
            "seniority": "SENIOR",
            "employmentStartDate": "2019-03-11",
            "hiringOrganization": "Company X",
            "qualifications": "<p>Masters Degrees in Sales Management</p>",
            "responsibilities": "<p>Entire department</p>",
            "incentives": "<p>Bus ticket</p>",
            "contact": "contact information goes here"
        }
    ]
}

GET /positions/public/vacancies/

Description: Find all the vacancy according of the required parameters

Parameters

Name Description Required Schema
companyId Your company ID Yes string
sortBy No string
page The current page number. Zero-indexed, so the first page is 0 No integer
pageSize How many items are in each page. Default value is 10 No integer

Responses

Code Description Schema
200 Successful operation PublicVacancy
403 Invalid permissions. The key you are using is incorrect, or do not have permissions for that operation

Vacation & Absence


Get Vacation and Absence Types

curl 'https://api.heavenhr.com/api/v2/company/absences/types -X GET' 

> The above command returns JSON structured like this:

{
    "data": [
        {
            "typeId": "1",
            "type": "Urlaub",
            "vacationType": "HOLIDAY",
            "colorCode": "#cddc39",

        },
        {
            "typeId": "2",
            "type": "Unbezahlter Urlaub",
            "vacationType": "UNPAIDLEAVE",
            "colorCode": "#fdd835",

        },
    ],

}

GET company/absences/types/

Description: Find all the absence types for the company.

Parameters

Name Description Required Schema

Responses

Code Description Schema
200 Successful operation AbsenceType
403 Invalid permissions. The key you are using is incorrect, or do not have permissions for that operation

Get Company Vacations and Absences

curl 'https://api.heavenhr.com/api/v2/company/absences?page=0&pageSize=100&startDate=2019-07-01&endDate=2019-07-30&status=REJECTED,APPROVED -X GET' 

> The above command returns JSON structured like this:

{
    "data": [
        {
            "employeeId": "1",
            "firstName": "Jurgen",
            "lastName": "Klopp",
            "startDate": "2019-07-01",
            "endDate": "2019-07-07",
            "budgetUsed": true,
            "numberOfDays": 5,
            "absenceType": "ILLNESS",
            "status": "APPROVED",
            "exceedBudget": false,
            "departmentId": 1,
            "comments": [
                {
                    "companyId": "1",
                    "ownerId": "1",
                    "ownerType": "ABSENCE_REQUEST",
                    "userId": "1",
                    "userFullName": "Admin",
                    "text": "this is a sample comment\n",
                    "creationDate": "2019-06-13T12:58:12.152"
                }
            ],

        }
    ],
    "meta": {
        "page": 0,
        "pageSize": 1,
        "count": 1
    },

}

GET company/absences/

Description:

Parameters

Name Description Required Schema
startDate Start date Yes Format is YYYY-MM-DD
endDate End date Yes Format is YYYY-MM-DD
status One or more of these statuses. PLANNED, REQUESTED, APPROVED, REJECTED, WITHDRAWN Yes
page The current page number. Zero-indexed, so the first page is 0 Yes integer
pageSize How many items are in each page. Default value is 10 Yes integer

Responses

Code Description Schema
200 Successful operation AbsenceRecord
403 Invalid permissions. The key you are using is incorrect, or do not have permissions for that operation

Get Employee Vacations and Absences

curl 'https://api.heavenhr.com/api/v2/employees/{employee_id}/absences/?page=0&pageSize=100&startDate=2019-07-01&endDate=2019-07-30&status=REJECTED,APPROVED -X GET' 

> The above command returns JSON structured like this:

{
    "data": [
        {
            "employeeId": "1",
            "firstName": "Jurgen",
            "lastName": "Klopp",
            "startDate": "2019-07-01",
            "endDate": "2019-07-07",
            "budgetUsed": true,
            "numberOfDays": 5,
            "absenceType": "ILLNESS",
            "status": "APPROVED",
            "exceedBudget": false,
            "departmentId": 1,
            "comments": [
                {
                    "companyId": "1",
                    "ownerId": "1",
                    "ownerType": "ABSENCE_REQUEST",
                    "userId": "1",
                    "userFullName": "Admin",
                    "text": "this is a sample comment\n",
                    "creationDate": "2019-06-13T12:58:12.152"
                }
            ],

        }
    ],
    "meta": {
        "page": 0,
        "pageSize": 1,
        "count": 1
    },

}

GET employees/{employee_id}/absences/

Description: Find all the absences and vacations for the employee according to the provided parameters.

Parameters

Name Description Required Schema
employeeId Employee Id Yes string
startDate Start date Format is YYYY-MM-DD Yes date
endDate End date Format is YYYY-MM-DD Yes date
status One or more of these statuses. PLANNED, REQUESTED, APPROVED, REJECTED, WITHDRAWN Yes string
page The current page number. Zero-indexed, so the first page is 0 Yes integer
pageSize How many items are in each page. Default value is 10 Yes integer

Responses

Code Description Schema
200 Successful operation AbsenceRecord
403 Invalid permissions. The key you are using is incorrect, or do not have permissions for that operation

Models


EmployeeCreated

Name Type Description Required
id string No
email string Yes

EmployeeUpdate

Name Type Description Required
gender string No
professionalEmail string The professional email of the employee No
email string The private email of the employee No

EmployeeSimple

Name Type Description Required
id string No
firstName string No
lastName string No
employeeNumber string No
jobStatus string No
updatedAt dateTime No
departmentName string No
departmentId string No
email string Yes

EmployeeCreatedRequest

Name Type Description Required
gender string No
professionalEmail string No
email string Yes
firstName string Yes
lastName string Yes
phonePersonal string No
mobileWork string No
streetPersonal string Home address street No
streetNumberPersonal string Home address number No
dateOfBirth date Format is YYYY-MM-DD No
nationality string No
additionalContractInformation string This field is a free text field for any comments on the contract. No
employeeNumber string This is a unique employee number No
jobStatus string No
jobTitle string No
occupation string No
locationId string This is the id of the location from the endpoint /company/locations Yes
permanentOrTemporary string This is whether the employee is fixed contract or has a temporary contract No
employmentType string No
startDate date Format is YYYY-MM-DD No
endOfContract date Format is YYYY-MM-DD No
fullTimeOrPartTime string No
costCenterId string The id of the cost centre the employee belongs to. This is the id from the endpoint /company/cost-centers No
departmentId string The id of the department the employee belongs to. This is the id from the /company/organizations No
sendOnboardingEmail boolean If you want to send onboarding email for the employee, default is False No
customerAttributes Array Custom attributes defined for employees on company level No
contract Contract Contract details for the employee No
workSchedule WorkSchedule Create a work schedule for the employee No

CreateEmployeeResponse

Name Type Description Required
errors [ object ] No
employee EmployeeCreated No

PagedEmployeeResponse

Name Type Description Required
page integer No
pageSize integer No
totalItems long No
totalPages integer No
data [ EmployeeSimple ] No

CompanyResponse

Name Type Description Required
id string No
name string No
customAttributes [ CustomAttributes ] No

CustomAttributes

Name Type Description Required
id string No
name string No
type string No
category string No

Organization

Name Type Description Required
id string No
name string No
pathName string No
headsOfUnit [ string ] No
children [ Organization ] No

PagedOrganizationResponse

Name Type Description Required
page integer No
pageSize integer No
totalItems long No
totalPages integer No
data [ Organization ] No

Location

Name Type Description Required
id string No
name string No
city string No
country string No

PagedLocationResponse

Name Type Description Required
page integer No
pageSize integer No
totalItems long No
totalPages integer No
data [ Location ] No

CostCenter

Name Type Description Required
id string No
name string No
number string No
employeeCount integer No

PagedCostCenterResponse

Name Type Description Required
page integer No
pageSize integer No
totalItems long No
totalPages integer No
data [ CostCenter ] No

TimeTrackingCreateRequest

Name Type Description Required
projectId string time tracking project Id No
startDate string Request Start Date Yes
endDate string Request End Date Yes
startTime string Yes
endTime string Yes
totalTimeInMinutes string No
breakTimeInMinutes string No
comment string No
status string No
categories string List of categories Ids No

TimeTrackingCreateResponse

Name Type Description Required
timeTracking TimeTrackingCreateResponse No

TimeTrackingRequest

Name Type Description Required
id string Yes
projectId string time tracking project Id No
requestDate string Request Date Yes
startTime string Yes
endTime string Yes
totalTimeInMinutes string No
breakTimeInMinutes string No
comment string No
status string Request Status Yes
categories string List of categories Ids No

Projects

Name Type Description Required
id string time tracking project id Yes
name string time tracking project name Yes
status string Project Status Yes

TimeTrackingStatus

Name Type Description Required
status string Time tracking Status has to be one of the following values REQUESTED, APPROVED, REJECTED Yes

PagedTimeTrackingRequest

Name Type Description Required
page integer No
pageSize integer No
count integer No
data [ TimeTrackingRequest ] No

Contract

Name Type Description Required
grossSalary double Gross salary Yes
settlementPeriodSalary string Settlement period for the salary Yes
holidaysPerYear string Numbers of holidays per year Yes
workingHoursPerWeek string Working hours per week Yes
probationPeriod string Probation period duration Yes
noticePeriodDuringProbation string Notice period during probation duration Yes
noticePeriodDuringProbationStart string Yes

WorkSchedule

Name Type Description Required
scheduledDate date Start date of the work schedule. Pattern: yyyy-MM-dd Yes
days Day List of days for the work schedule Yes
defaultSchedule boolean If is the default work schedule of the employee No

Day

Name Type Description Required
dayOfWeek string The day of the week Yes
worktimeInMinutes integer Work time in minutes for the day Yes

PayrollPeriodPagedResponse

Name Type Description Required
page integer The current page number. Zero-indexed, so the first page is 0 No
pageSize integer How many items are in each page No
totalItems long How many items were found in total No
totalPages integer Total number of pages No
data [PayrollPeriod] List of payroll periods No

PayrollPeriod

Name Type Description Required
id string Id of the payroll period No
dateStart date The start date of the payroll period No
dateEnd date The end date of the payrolld period No
status string Status of the payroll period, status has one of the two values OPEN, CLOSED No

PagedPayrollPeriodSalaryDetailsresponse

Name Type Description Required
page integer The current page number. Zero-indexed, so the first page is 0 No
pageSize integer How many items are in each page No
totalItems long How many items were found in total No
totalPages integer Total number of pages No
data [SalaryDetails] List of all salary detials for the payroll period No

SalaryDetails

Name Type Description Required
employeeId string No
firstName string No
personelNumber string No
salary [Salary] Salary details No

Salary

Name Type Description Required
fixedSalary long No
others long No

PagedShiftResponse

Name Type Description Required
page integer The current page number. Zero-indexed, so the first page is 0 No
pageSize integer How many items are in each page No
totalItems long How many items were found No
totalPages integer The total number of pages No
data [Shift] List of shifts No

Shift

Name Type Description Required
id string Id of the shift Yes
startTime dateTime Date and time when the shift started Yes
endTime dateTime Date and time when the shift ended Yes
status string The status can be one of the two values DRAFT or PUBLISHED Yes

PagedShiftCompanyResponse

Name Type Description Required
page integer The current page number. Zero-indexed, so the first page is 0 No
pageSize integer How many items are in each page No
totalItems long How many items were found No
totalPages integer The total number of pages No
data [CompanyShift] List of shifts No

CompanyShift

Name Type Description Required
id string Id of the shift No
startTime dateTime Date and time when the shift started No
endTime dateTime Date and time when the shift ended No
assignedUsers string Assigned users Id list No
status string The status can be one of the two values DRAFT or PUBLISHED No

ShiftDetail

Name Type Description Required
id string Id of the shift No
breakInMinutes long No
totalInMinutes long No
type [ShiftType] No
startTime dateTime Date and time when the shift started No
endTime dateTime Date and time when the shift ended No
assignedUsers string Assigned users Id list No
status string The status can be one of the two values DRAFT or PUBLISHED No
orgaUnits string Ids of applicable organization units No
occupations [Occupation] List of occupations No
shortHanded boolean If the shift is short handed No

ShiftType

Name Type Description Required
id string Id of the type No
name string Name of the shift type No
status string Status has one of the following values ACTIVE, INACTIVE, ARCHIVED No

Occupation

Name Type Description Required
name string Name of the occupation No
count integer Amount of the occupation No

PagedCategoriesResponse

Name Type Description Required
page integer The current page number. Zero-indexed, so the first page is 0 No
pageSize integer How many items are in each page No
totalItems long How many items were found No
totalPages integer The total number of pages No
data [Category] List of categories No

Category

Name Type Description Required
id string Id of the category No
name string Name of the category No
status string Status has one of the following values ACTIVE, INACTIVE, ARCHIVED No

PublicVacancyItem

Name Type Description Required
id string Id of the category No
email string No
jobTitle string No
employmentTypes [EmploymentType] A list of EmploymentType No
location string The location of the vacancy No
department string The department name No
publicationDate date No
status [VacancyStatus] The status of the Vacancy No
industry [Industry] No
fieldOfWork [FieldOfwork] No
positionType [PositionType] No
seniority [Seniority] No
employmentStartDate date The date the employee should start No
hiringOrganization string No
qualifications string No
responsibilities string No
incentives string No
contact string No

PublicVacancy

Name Type Description Required
id string Id of the public vacancy No
jobTitle string No
description string No
employmentTypes [EmploymentType] A list of EmploymentType No
numberOfOpenings integer No
location string The location of the vacancy No
department string The department name No
publicationDate date No
numberOfApplicants integer No
companyId string No
status [VacancyStatus] The status of the Vacancy No
industry [Industry] No
fieldOfWork [FieldOfwork] No
positionType [PositionType] No
seniority [Seniority] No
employmentStartDate date The date the employee should start No
hiringOrganization string No
qualifications string No
responsibilities string No
incentives string No
contact string No

EmploymentType

Name Type Description Required
type string EmploymentType has one of the following values FULL_TIME, PART_TIME, CONTRACT, TEMPORARY, WORKING_STUDENT, INTERNSHIP, TRAINEE, FREELANCER, SHORT_TERM_EXTERNAL_LOAN, OTHER No

VacancyStatus

Name Type Description Required
status string VacancyStatus has one of the following values DRAFT, PUBLISHED, ARCHIVED No

Industry

Name Type Description Required
name string Type of the industry examples: Oil, It, Telecommunications No

FieldOfwork

Name Type Description Required
name string Field of work for the vacancy examples: Logistics, Law, Service, Sales No

Seniority

Name Type Description Required
name string The required seniority for the vacancy No

AbsenceType

Name Type Description Required
typeId string The id of the absence type No
type string The type of absence No
vacationType string The vacation type for the absence. HOLIDAY, UNPAIDLEAVE, OVERTIME, ILLNESS, SPECIALLEAVE No
colorCode string Color code for the absence No

AbsenceRecord

Name Type Description Required
employeeId string The id of the employee No
firstName string The first name of the employee No
lastName string The last of the employee No
startDate date The date when the absence was started No
endDate date The date when the absence was ended No
budgetUsed double Budget of the absences that was used for this absence No
numberOfDays double Number of days of absence No
absenceType string Type of absence No
status string Status of the absence. PLANNED, REQUESTED, APPROVED, REJECTED, WITHDRAWN No
comments [Comment] The comment for the absence No
departmentId string Department id of the employee No
exceedBudget boolean Budget was exceeeded or not for this absence No

Comment

Name Type Description Required
companyId string Company id for which comment was created No
ownerId string Owner id of the comment No
ownerType string Owner type of the comment No
userId string User id of the user No
userFullName string Name of the user who wrote this comment No
text string Text of the comment No
creationDate date The date when the comment was created No

Errors

The HeavenHR API uses the following error codes:

Error Code Meaning
400 Bad Request -- Your request is invalid.
401 Unauthorized -- Your API key is wrong.
403 Forbidden -- The API requested is hidden for administrators only.
404 Not Found -- The specified entity could not be found.
405 Method Not Allowed -- You tried to access an API with an invalid method.
406 Not Acceptable -- You requested a format that isn't json.
429 Too Many Requests -- You're requesting too many Information! Slow down!
500 Internal Server Error -- We had a problem with our server. Try again later.
503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.