Guides
Signup For Free

HeavenHR API Integration

Suggest Edits

These are the list of integration use cases supported by Knit for HeavenHR API as part of the HRIS category

Get all employees

  • ID: get_all_employees
  • Operation: read
  • Entities: department, employee, job status
  • Summary: The 'Get all employees' API returns a list of employees with limited fields. It supports pagination and filtering by various parameters such as page number, page size, employee number, department ID, job status, start date, and updated date. The request requires an 'Authorization' header with the API key in 'Basic heaven_hr_api_key' format. The response includes the current page, page size, total items, total pages, and a list of employee data with fields like ID, first name, last name, employee number, job status, updated time, department name, department ID, and email. The response headers include 'X-B3-SpanId' for tracking requests. The API returns a 200 status code on success and a 404 status code if no employees are found for the specified page.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

Get all shifts for an employee

  • ID: get_all_shifts_for_an_employee
  • Operation: read
  • Entities: shift, employee, date
  • Summary: This API retrieves all shifts for a specified employee within a given date range. The request requires the employee ID as a path parameter and the start and end dates as query parameters in ISO date format (yyyy-MM-dd). The request headers must include an Authorization key in the format 'Authorization: Basic heaven_hr_api_key'. The response includes pagination details and a list of shifts, each with an ID, start and end times, and status. A successful response returns a 200 status code with the shift data, while a 404 status code indicates that the employee was not found. The response headers include an X-B3-SpanId for tracking the specific request.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

Get All Vacancies

  • ID: get_all_vacancies
  • Operation: read
  • Entities: department, vacancy, organization
  • Summary: The Get All Vacancies API allows users to retrieve a list of job vacancies based on specified query parameters. The required parameter is 'companyId', which is the ID of the company. Optional parameters include 'sortBy' for sorting the results, 'page' for pagination, and 'pageSize' to specify the number of items per page. The response includes detailed information about each vacancy, such as job title, location, department, publication date, and more. A successful response returns a status code of 200 with a list of vacancies, while a 403 status code indicates invalid permissions.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

Get categories for time tracking

  • ID: get_categories_for_time_tracking
  • Operation: read
  • Entities: time tracking, category, company
  • Summary: This API endpoint returns a list of categories for time tracking. It supports pagination through the 'page' and 'pageSize' query parameters, which are both optional. The response includes the current page number, the number of items per page, the total number of items, the total number of pages, and an array of category objects. Each category object contains an 'id', 'name', and 'status'. A successful response returns a status code of 200, while a 403 status code indicates invalid permissions.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

Get Company Info

  • ID: get_company_info
  • Operation: read
  • Entities: employee, custom attribute, company
  • Summary: The Get Company Info API retrieves information about a company, including any custom attributes that have been defined. The request requires an Authorization header with a personal API key. The format should be 'Authorization: Basic heaven_hr_api_key', where 'heaven_hr_api_key' is replaced with your personal API key. The response includes the company's unique identifier, name, and a list of custom attributes, each with its own ID, name, type, and category. Additionally, the response headers include an X-B3-SpanId for tracking the specific request. This API does not require any path or query parameters and returns a JSON object containing the company data.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

Get Company Locations

  • ID: get_company_locations
  • Operation: read
  • Entities: location, company
  • Summary: The Get Company Locations API returns a list of locations for a company. It accepts optional query parameters 'page' and 'pageSize' to paginate the results. The response includes the total number of items, total pages, and an array of location data, each containing the city, id, name, and country of the location. A successful response returns a status code of 200, while a 404 status code indicates no location information was found for the requested page.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

Get Company Payroll Periods

  • ID: get_company_payroll_periods
  • Operation: read
  • Entities: payroll period, company
  • Summary: The Get Company Payroll Periods API retrieves all payroll periods for a company, including both current and closed periods. It supports pagination through the 'page' and 'pageSize' query parameters, which are optional. The response includes details such as the page number, page size, total items, total pages, and an array of payroll period data. Each payroll period includes an ID, start date, end date, and status. A successful response returns a 200 status code, while a 403 status code indicates invalid permissions.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

Get Company Vacations and Absences

  • ID: get_company_vacations_and_absences
  • Operation: read
  • Entities: employee, absence, company
  • Summary: The Get Company Vacations and Absences API allows users to retrieve information about employee absences within a company. The API requires query parameters such as startDate, endDate, status, page, and pageSize to filter and paginate the results. The response includes detailed information about each absence, including employee details, absence type, status, and any comments associated with the absence. The API returns a 200 status code for successful operations and a 403 status code if the user does not have the necessary permissions.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

Get Cost Centers

  • ID: get_cost_centers
  • Operation: read
  • Entities: cost center, company
  • Summary: The Get Cost Centers API returns a list of cost centers for a company. It accepts optional query parameters 'page' and 'pageSize' to paginate the results. The response includes the current page number, the number of items per page, the total number of items, the total number of pages, and a list of cost centers with details such as id, number, name, and employee count. A successful response returns a status code of 200, while a 404 status code indicates no cost center information was found for the requested page.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

Get detailed shift

  • ID: get_detailed_shift
  • Operation: read
  • Entities: shift, occupation, user
  • Summary: The 'Get detailed shift' API retrieves detailed information about a specific shift identified by the 'shift_id' path parameter. The request requires the 'shift_id' to be provided as a path parameter. The response includes details such as the shift's unique ID, break duration, total duration, type, start and end times, assigned users, status, organizational units, occupations, and whether the shift is short-handed. A successful response returns a status code of 200 with the shift details, while a 404 status code indicates that the shift was not found.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

Get Employee Details by ID

  • ID: get_employee_details_by_id
  • Operation: read
  • Entities: work schedule, employee, contract
  • Summary: This API retrieves the details of an employee by their ID. The request requires the 'id' path parameter, which is the unique identifier of the employee, and an 'Authorization' header containing the API key. The response includes comprehensive details about the employee, such as personal information, job title, employment type, contact details, contract specifics, and work schedule. The response headers include 'X-B3-SpanId' for tracking the specific request. The API returns a 200 status code on success, a 400 status code if the ID is invalid, and a 404 status code if the employee is not found.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

Get Employee Time Tracking Requests

  • ID: get_employee_time_tracking_requests
  • Operation: read
  • Entities: time tracking request, employee, category
  • Summary: This API retrieves the time tracking requests for a specific employee using their unique employee ID. The request requires an Authorization header with a valid API key. The response includes a list of time tracking requests, each with details such as request date, start and end times, total and break times, comments, status, and associated categories. The response also includes pagination metadata and a Span ID for tracking the request.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

Get Employee Vacations and Absences

  • ID: get_employee_vacations_and_absences
  • Operation: read
  • Entities: employee, vacation, absence
  • Summary: The Get Employee Vacations and Absences API retrieves all absences and vacations for a specified employee based on the provided parameters. The request requires the employee ID as a path parameter and several query parameters including startDate, endDate, status, page, and pageSize. The response includes a list of absence records with details such as employee name, absence type, status, and comments. The response also includes pagination metadata.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

Get Organizations

  • ID: get_organizations
  • Operation: read
  • Entities: structure, organization, company
  • Summary: The Get Organizations API allows users to traverse the hierarchical structure of a company by returning the company structure tree. It is accessed via a GET request to the endpoint 'https://api.heavenhr.com/api/v2/company/organizations'. The API does not require any headers, path parameters, query parameters, or request body. On a successful request, it returns a JSON object with a 'data' field containing an array of organization units. Each unit has properties such as 'headsOfUnit', 'pathName', 'children', 'name', and 'id'. The response code 200 indicates success, while a 404 response code indicates that no company organization structure information was found for the requested page.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

Get Payroll Period Salary Details

  • ID: get_payroll_period_salary_details
  • Operation: read
  • Entities: employee, salary detail, payroll period
  • Summary: The 'Get Payroll Period Salary Details' API retrieves all salary details for a specified payroll period. The API requires the 'payrollperiod_id' as a path parameter to identify the payroll period. Optional query parameters 'page' and 'pageSize' can be used to paginate the results. The response includes details such as employee ID, first and last names, personnel number, and salary information including fixed salary and other components. The API returns a paginated list of salary details, and handles errors such as invalid permissions (403) and not found (404) for incorrect payroll period IDs.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

Get shifts

  • ID: get_shifts
  • Operation: read
  • Entities: shift, user, company
  • Summary: The Get shifts API returns a list of shifts for a company. It requires the startDate and endDate as query parameters in ISO Date Format (yyyy-MM-dd) to define the search range. The status parameter is optional and can be either DRAFT or PUBLISHED, with a default value of PUBLISHED. The response includes pagination details such as page, pageSize, totalItems, and totalPages, along with the data array containing shift details like id, startTime, endTime, assignedUsers, and status. A successful response returns a 200 status code, while a 403 status code indicates invalid permissions.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

Get Sub Company Payroll Periods

  • ID: get_sub_company_payroll_periods
  • Operation: read
  • Entities: sub company, page, payroll period
  • Summary: This API retrieves all the payroll periods for a specified sub company, including both current and closed periods. The request requires the 'subcompany_id' as a path parameter. Optional query parameters include 'page' for the current page number (zero-indexed) and 'pageSize' for the number of items per page. The response includes pagination details and a list of payroll periods, each with an ID, start and end dates, and status. A successful response returns a 200 status code, while a 403 status code indicates invalid permissions.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

Get Time Tracking Projects

  • ID: get_time_tracking_projects
  • Operation: read
  • Entities: employee, time tracking, project
  • Summary: This API endpoint retrieves the time tracking projects for a specific employee identified by the employee_id path parameter. The request requires the employee_id to be specified in the URL path. On a successful request, it returns a list of projects associated with the employee, each containing an id, name, and status. If the employee is not found, a 404 error is returned.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

Get Time Tracking Request

  • ID: get_time_tracking_request
  • Operation: read
  • Entities: employee, time tracking, request
  • Summary: The 'Get Time Tracking Request' API retrieves the time tracking request details for a specific employee by their ID. The API requires two path parameters: 'employee_id', which is the ID of the employee who owns the time tracking request, and 'id', which is the ID of the specific time tracking request. Upon a successful request (HTTP 200), the API returns details such as the project ID, request date, status, start and end times, total and break times in minutes, any comments, and associated categories. If the employee or request ID is not found, a 404 error is returned.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

Get Vacancy

  • ID: get_vacancy
  • Operation: read
  • Entities: department, vacancy, position
  • Summary: The Get Vacancy API allows users to find a vacancy by its ID and retrieve all the details associated with that vacancy. The request requires a path parameter 'vacancy_id' which is mandatory. The response includes detailed information about the vacancy such as job title, description, employment types, number of openings, location, department, publication date, number of applicants, company ID, status, industry, field of work, position type, seniority, employment start date, hiring organization, qualifications, responsibilities, incentives, and contact information. The API returns a 200 status code for a successful operation, a 403 status code for invalid permissions, and a 404 status code if no vacancy is found for the given ID.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

Get Vacation and Absence Types

  • ID: get_vacation_and_absence_types
  • Operation: read
  • Entities: vacation type, absence type, company
  • Summary: The 'Get Vacation and Absence Types' API retrieves all the absence types available for a company. It does not require any input parameters. The response includes a list of absence types, each with a typeId, type, vacationType, and colorCode. A successful response returns a status code of 200 with the absence types data. If the request is made with invalid permissions, a 403 error is returned.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

Update Employee Details

  • ID: patch_update_employee_details
  • Operation: write
  • Entities: work schedule, employee, contract
  • Summary: The Update Employee Details API allows updating specific fields of an employee's record, including Contract and WorkSchedule details. The API requires the employee ID as a path parameter and an Authorization key in the headers. The request body can include various fields such as startDate, endOfContract, professionalEmail, jobTitle, and more. The response will return the updated employee details if successful, along with an X-B3-SpanId in the headers for tracking purposes. The API returns a 204 status code for success, 400 for invalid ID, and 404 if the employee is not found.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

Update the status of time Tracking Request

  • ID: patch_update_status_of_time_tracking_request
  • Operation: write
  • Entities: time tracking request, status, employee
  • Summary: This API endpoint is used to update the status of a time tracking request for a specific employee. The request requires three path parameters: 'employee_id', which is the ID of the employee who owns the time tracking request; 'id', which is the ID of the time tracking request to be updated; and 'status', which is the new status for the request and must be one of the following values: REQUESTED, APPROVED, or REJECTED. The API returns a response code and message indicating the result of the operation. A successful update returns a 200 status code with a 'Success' message. If an invalid ID is supplied, a 400 status code is returned, and if the employee or time tracking request is not found, a 404 status code is returned.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

Update Time Tracking Request

  • ID: patch_update_time_tracking_request
  • Operation: write
  • Entities: time tracking request, employee
  • Summary: The Update Time Tracking Request API allows you to update the details of a specific time tracking request for an employee. The API endpoint requires the employee_id and the id of the time tracking request as path parameters. The request headers must include an Authorization key. The request body can include optional fields such as projectId, startDate, endDate, startTime, endTime, total, breakTime, comment, and categories. The API will only update the fields that are sent in the request. The response will include the updated time tracking details and a header with a Span ID for tracking the request.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

Create a new employee

  • ID: post_create_a_new_employee
  • Operation: write
  • Entities: work schedule, employee, contract
  • Summary: This API allows you to add a new employee to your company and send an email for the employee to register with HeavenHR. The request requires a detailed body with employee information such as start and end dates of the contract, professional email, job title, personal address, location ID, employee number, gender, nationality, occupation, and more. The response will return the created employee details if successful. The API returns a 201 status code if the employee is created successfully, a 400 status code if the submitted employee record is invalid, and a 403 status code if there are invalid permissions. The request must include an Authorization header with your personal API key, and the response headers will include an X-B3-SpanId for tracking purposes.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

Create Absence Budget for an Employee

  • ID: post_create_absence_budget_for_an_employee
  • Operation: write
  • Entities: employee, absence budget
  • Summary: This API endpoint is used to create the budget for absence for a particular employee. It requires the employee's ID as a path parameter and the year for which the absence budget is being created as a request body parameter. The API uses the POST method and the endpoint URL is 'https://api.heavenhr.com/api/v2/employees/{id}/absencebudgets'. The 'id' parameter is required and should be a string representing the employee's ID. The 'year' parameter is also required and should be an integer representing the year.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

Create Time Tracking Request

  • ID: post_create_time_tracking_request
  • Operation: write
  • Entities: time tracking request, employee, project
  • Summary: This API endpoint allows you to add a new time tracking request for an employee. The request must include the employee ID in the path parameters and a JSON body with details such as project ID, start and end dates, start and end times, break time, status, and categories. The allowed statuses during creation are EDITABLE and REQUESTED. Upon successful creation, a 201 response is returned. If the request is invalid, a 400 response is returned, and if there are permission issues, a 403 response is returned.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

Updated about 1 month ago