API reference tips

Time tracking (clock in/out)

In our Reference section, we have two endpoints related to the Attendance module (time tracking). We are going to explain the difference between these two:

1. Attendance > V1
   This version is to GET the time tracking data of all users or POST the time tracking data live. For example, connect a clock-in device to Factorial.
   1. You cannot implement this version if you want to clock in before another open clock in
   2. You must have a clock out to POST a clock in
   3. There is no automation to place the clock out after XX hours. We don't offer this option in Factorial.
2. Attendance > V2
   This version is to GET the time tracking data of all users or POST the time tracking closed. This means, the time tracking must have a clock in and a clock out and applies to the past days.

• Spanish video Explaining time tracking endpoints.
• English video Explaining time tracking endpoints.

How can I GET the work areas (office)?

Depending on the call you are using to GET employees, you will be able to obtain the work area (office, workplace) of your users.

If you are using GET > Employee > V2

1. Get the employee data with V2
2. Go to CORE> Workplace> V2
   1. You can place the ID of the employees in this call to know the work area (office) of the employee
   2. Or you can GET all the workplaces areas and filter by workplaces

How can I create a new document (POST)? Version 2

You need to make sure to complete the minimum information to create a new document in Factorial.

-Public: Should documents be public or not?

-Space: Where this document should be placed?

If inside a folder, we need to place this in a folder ID in "Folder_id" property. You can obtain the list of folder IDs in the endpoint "Documents> Folder"

-Is_pending_assignment: Does this need to be pending in the employee profile? Yes/No

-Author_id: The author ID will be the Access ID of the employee that sent this document. This access ID is in the "Employee> Employee"

-Company_id: You can obtain this field from Legal entity endpoint

-Signee_ids: The signee_ID is the employee that will receive this document and has to sign the document as well. This will be the access_ID of the employee that has to sign the document. You can obtain this from "Employee> Employee"

How does custom fields endpoint work for employees? Version 1 (soon deprecated)

The custom fields are in a separate endpoint in our API. This is the endpoint where you can find all the custom fields about employees' data

Video with the explanation

How custom fields endpoint work with contracts? Version 1 (soon deprecated)

You need to check the GET custom fields V1.

If you want to obtain the contract fields values, you need to place in the instance_id the contract version of the employee.

Where you can fetch the contract version? From the Payroll > contracts endpoint

How can I get the information about contracts?

1. Go to PAYROLL > Contracts To obtain all contracts of your employees.
2. If you want to obtain for certain employees (filter by the employee) > [go to reference contracts](https://apidoc.factorialhr.com/reference/get_v1-payroll-reference-contracts

Obtain the estimated hours of the employees

The endpoint will depend on the time planning chosen for the employee. The time planning can be checked in the UI (Employee > Time planning > tool)

Endpoints available

Contracts

• Endpoint Payroll>Contracts: https://apidoc.factorialhr.com/reference/get_v1-payroll-contract-versions
• Video explaining how contracts works

Shift management

• Endpoint Shift management: https://apidoc.factorialhr.com/reference/get_v1-time-shifts-management
• Video explaining how shift management and time zones work in the API

Work schedules

• Endpoint: https://apidoc.factorialhr.com/v2.0/reference/get_api-v2-resources-work-schedule-schedules
• Video explaining how this works.

Shift management

The API doesn’t support times with timezones, we’ll parse that as UTC so we’ll drop the "+02:00". We will use the time zone of the main location of the user, which means this is linked to the workplace (location_id) of the user.

For example, if the user has 3 workplaces assigned and by rule, one of them will be the main one. When we try to POST a new shift, even if we decide the location_id, the time zone will be the one of the main location.

Power Bi

You will find all the necessary steps to connect with Power Bi in this PDF

Holidays

Regarding holidays, you can obtain the number of days the employee takes.

1. Time > leaves are the endpoints you should use.
   1. Get leave by ID will filter the employee you are looking for (remember this should be done with the ID you obtain in the GET call)
2. Time> Leave Types you will obtain all the information of your leave types.

Webhooks

Click here, to find our complete explanation regarding Webhooks and in this link to create your first webhook

Click here to see how to set up your first webhook.