HomeGuidesAPI ReferenceChangelogDiscussions
Guides

API reference V2

FAQs on general questions about our API

Suggest Edits

Employee module

How GET teams work?

The endpoint to GET teams will retrieve all the employees (active/terminated) from the Factorial account. This means that you could see 2 team leads (lead_ids) in the response, but in the UI you only see one.

Where we can GET the job titles?

All job titles are posted in Contract versions endpoints.

Remember that each employee can have several contract versions in Factorial. So, you need to GET the last contract version of each employee to make sure you have the latest job title.

Important: "job_catalog_level" & "job_catalog_role" will be deprecated from this endpoint. All information will show as null.

Step by step

In the /api/2024-10-01/resources/contracts/contract_versions endpoint you will find the job_catalog_level_id field with the ID of the level:

For example "job_catalog_level_id": 8,

With the previous id, you will have to search for it in the Job catalog: /api/2024-10-01/resources/job_catalog/levels/:id

{
"id": 1,
"role_id": 1,
"name": "Junior Engineer",
"role_name": "Engineering",
"order": 0,
"archived": false,
"is_default": false
},
You will find the role name "Engineering" (old job_catalog_role field) and the name of the level "Junior Engineer" (old job_catalog_level field)

We have inside Job Catalog > Roles the option to request role information directly from there: /api/2024-10-01/resources/job_catalog/roles/ and /api/2024-10-01/resources/job_catalog/roles/:id


Employee custom field

How to obtain the employee custom field (GET) with our API > Video (EN)


Custom tables

How can I obtain a custom table? In this short video, we will explain what are the custom tables and how to obtain them with the API.


Documents module

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 endpoint"

Important: Access_ID and Employee_ID are not the same.

Yellow arrow = Employee_ID & Green arrow = Access_id


-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"


Time module

Time off allowances incidence

Allowances it's a counter inside a time off policy.

Each counter will have an ID obtained from this endpoint: https://apidoc.factorialhr.com/reference/get_api-v2-resources-timeoff-allowances

For example: "id": 178281, "name": "Autorización de ausencias",

Now, the allowance incidence shows the manual adjustments done in each employee time off. The endpoint will share the employee ID, the allowance and the ID of that time off adjustment done by them.

Video with the explanation


How we connect time off policy, allowance and leave type?

It's important to understand that a leave type is inside a time off allowance and the time off allowance inside a time off policy.

First, you need to know which employee and leave you are looking for with Employee> Leave endpoint. Then you search for the leave type endpoint to know which is the allowance it belongs to (it can have several allowances).

Then we can search for the allowance ID and detect the time off policy it belongs to. Remember that a time off policy has several time off allowances.

This is an example on how to search the time off policy inside the allowance endpoint


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

Shift management

Work schedules

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.

How to create breaks in the past?

You can have a look at the Attendance> Shift >Create endpoint.

You will see that one of the field called workable: If you leave this blank or set it to true, means a workable shift. If it’s false, it means a break 👌



Integrations

Power Bi

You will find all the necessary steps to connect with Power Bi in this the Help Center.

Webhooks

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

Updated 8 days ago