This guide introduces how to set up time-off tracking in your system with Marco. The two main procedures are:

The guide will walk you through the two procedures, with examples of how you can use Marco API.

Prepare the necessary data so that your system is ready to begin tracking time-off records and leave balances with Marco API. The calculation of the staff's leave balances requires the following data:

To configure the required data, the following tasks should be completed:

Begin by creating a country-specific leave policy for every country you have employees in. Marco has a global data cloud containing leave type information:

You can make use of Marco's data cloud to create your company's leave policy. Based on this policy document, Marco will automatically generate the correct leave item data for each staff, including the leave types, effective date, entitlement amount, carry over amount, and more.

The leave type names used in your company's system should match with Marco's multilingual global dictionary of leave types. Currently, only English and Chinese are supported.

To start tracking time-off records for an employee, the employee must first be added to Marco. Use the Create or update user information endpoints to set up the employees in Marco.

There are four identifying parameters involved in adding employees. To begin, customer_id is your company's unique Marco identifier, which is required to match and verify that the API caller is authorized to add employees to your company.

In addition, the following parameters must be unique for each employee:

To create an employee, customer_system_id and system_email must not already exist in the system. When updating an employee, customer_system_id and customer_system_id_type will be used to identify the employee.

Other than the four identifying parameters, you can specify as much data when adding an employee. The minimum data required to add an employee to Marco includes:

Example

To ensure correct leave balances for the year, existing time-off records should be imported into Marco. The data should be stored in a .csv file and sent to Marco's technical team for import.

Once the necessary requirements have been configured, you can use Marco API to start tracking leave requests and balances for all staff.

When a staff applies for leave on your system, the following endpoints are involved:

With the new time-off record, the staff's leave balance will be updated.

During approval, the following endpoints are involved:

If the request is rejected, the staff's leave balance will update accordingly.

To support systems globally, employees can apply for leave in their preferred language. Marco API currently supports English and Chinese.

Use the Get leave items endpoints to retrieve the leave balance and other leave item details. For example, the endpoints all return the following numbers for display:

When the staff is applying for leave, you can implement additional checks, such as whether the staff has sufficient balance.

Use the Calculate total leave days endpoint to get the total number of leave days in the leave request. Based on the given country, the calculation will automatically account for its weekend days and public holidays.

The number of leave days can be checked against the staff's leave balance to determine if the staff can apply for time off.

Use the Add time-off record endpoint to add the leave request to Marco. When submitting a leave request, the following fields should be left empty:

Once submitted, the requested number of leave days will be automatically deducted from the staff's current leave balance.

Use the Edit time-off record endpoint to approve or reject leave requests:

If a leave request has been rejected, the requested number of leave days will be automatically released back to the staff's current leave balance.