We are happy to announce the new v2025-01-01 (Fourier) version has been released. Most of the API remains the same, with updated endpoint paths.

As you know, our versions are named after famous numeric series. The Fourier series is renowned for breaking down complex patterns into simple, steady components. Similarly, this release reflects our commitment to clarity and dependability, ensuring our endpoints work seamlessly and reliably.

The most relevant parts are Performance endpoints and webhooks. Other additions are contract type endpoints and improvements in Ats, Attendance, Employees, Expenses, Teams, and Project Management resources.

Don't miss out on the news it brings and read the detailed Changelog

Ats > Application

An application for a job in the ATS

Applies an Application

New Endpoint

Ats > Hiring stage

Logical grouping for phases used for all job openings

Reads a single Hiring stage request

New Field ats_application_phase_id has been added
Identifier of the application phase that belongs to a hiring stage

Attendance > Shift

Shift operations

All Responses

New Field updated_at has been added
Timestamp when the shift record was updated

Contracts > French contract type

Available contract types in France

Reads all French contract types

New Endpoint

Contracts > German contract type

Available contract types in Germany

Reads all German contract types

New Endpoint

Contracts > Portuguese contract type

Available contract types in Portugal

Reads all Portuguese contract types

New Endpoint

Contracts > Spanish contract type

Available contract types in Spain

Reads all Spanish contract types

New Endpoint

Employees > Employee

Employee

Updates an Employee request

New Field identifier_expiration_date has been added
Identifier expiration date

Create with contracts an Employee request

New Field identifier_expiration_date has been added
Identifier expiration date.

All Responses

New Field identifier_expiration_date has been added
Identifier expiration date

Expenses > Mileage

Represents a mileage

All Responses

New Field origin_longitude has been added
The longitude of the origin of the mileage

New Field origin_latitude has been added
The latitude of the origin of the mileage

New Field destination_longitude has been added
The longitude of the destination of the mileage

New Field destination_latitude has been added
The latitude of the destination of the mileage

New Field calculated_mileage has been added
The calculated mileage between origin and destination in decameters/10-milers

Performance > Agreement

Performance Agreements

All Responses

New Field self_comments has been added
Self comments by question

New Field manager_comments has been added
Manager comments by question

New Field self_evaluation_id has been added
Self review evaluation id

New Field manager_evaluation_id has been added
Manager review evaluation id

Removed Field reviewer_access_id has been removed

Removed Field manager_questionnaire has been removed

Removed Field self_questionnaire has been removed

Performance > Company employee score scale

Performance Company Employee Score Scales

Reads all Company employee score scales

New Endpoint

Sets a Company employee score scale

New Endpoint

Performance > Employee score scale

Performance Employee Score Scales

Reads all Employee score scales

New Endpoint

Performance > Review employee score

Performance Review Employee Scores

Reads all Review employee scores

New Endpoint

Performance > Review process

Performance Review Process

Remind in bulks a Review process request

New Field evaluation_types has been added
Reviewer strategies to remind about

Creates a Review process request

New Field competencies_assessments_enabled has been added
Whether the competencies assessments are enabled or not. this will allow assessing competencies for self and manager evaluations

All Responses

New Field competencies_assessments_configuration has been added
Configuration of the competencies assessments feature

Update competencies assessments configurations a Review process

New Endpoint

Update employee score configurations a Review process

New Endpoint

Schedules a Review process

New Endpoint

Remove schedules a Review process

New Endpoint

ProjectManagement > Project

Project Management Projects

Reads a single Project request

New Field no_clients has been added
Retrieve only the projects that are not related to any client.

Creates a Project request

New Field client_id has been added
Client associated to the project

All Responses

New Field total_cost_cents has been added
Total cost in cents

ProjectManagement > Project task

Reads a single Project task request

New Field due_status has been added
Retrieve only the project tasks that their due status match with the content passed as argument.

Teams > Team

Teams

Reads a single Team request

New Field ids has been added

WorkSchedule > Overlap period

Represents a specific time frame where a schedule applies. It has a day and month for for beginning and end, but not a year: it is assumed it repeats every year at the same dates.

Reads a single Overlap period request

New Field ids has been added
List of identifiers of the overlap periods

Webhooks

Attendance > Shift > Autofills

Payloads

New Field updated_at has been added
Timestamp when the shift record was updated

Attendance > Shift > Break ends

Payloads

New Field updated_at has been added
Timestamp when the shift record was updated

Attendance > Shift > Break starts

Payloads

New Field updated_at has been added
Timestamp when the shift record was updated

Attendance > Shift > Clock ins

Payloads

New Field updated_at has been added
Timestamp when the shift record was updated

Attendance > Shift > Clock outs

Payloads

New Field updated_at has been added
Timestamp when the shift record was updated

Attendance > Shift > Creates

Payloads

New Field updated_at has been added
Timestamp when the shift record was updated

Attendance > Shift > Deletes

Payloads

New Field updated_at has been added
Timestamp when the shift record was updated

Attendance > Shift > Toggle clocks

Payloads

New Field updated_at has been added
Timestamp when the shift record was updated

Attendance > Shift > Updates

Payloads

New Field updated_at has been added
Timestamp when the shift record was updated

Employees > Employee > Create with contracts

Payloads

New Field identifier_expiration_date has been added
Identifier expiration date

Employees > Employee > Invites

Payloads

New Field identifier_expiration_date has been added
Identifier expiration date

Employees > Employee > Terminates

Payloads

New Field identifier_expiration_date has been added
Identifier expiration date

Employees > Employee > Unterminates

Payloads

New Field identifier_expiration_date has been added
Identifier expiration date

Employees > Employee > Updates

Payloads

New Field identifier_expiration_date has been added
Identifier expiration date

Performance > ReviewProcess > Creates

Payloads

New Field competencies_assessments_configuration has been added
Configuration of the competencies assessments feature

Performance > ReviewProcess > Deletes

Payloads

New Field competencies_assessments_configuration has been added
Configuration of the competencies assessments feature

Performance > ReviewProcess > Duplicates

Payloads

New Field competencies_assessments_configuration has been added
Configuration of the competencies assessments feature

Performance > ReviewProcess > Remind in bulks

Payloads

New Field competencies_assessments_configuration has been added
Configuration of the competencies assessments feature

Performance > ReviewProcess > Remove schedules

Payloads

New Field competencies_assessments_configuration has been added
Configuration of the competencies assessments feature

Performance > ReviewProcess > Reopens

Payloads

New Field competencies_assessments_configuration has been added
Configuration of the competencies assessments feature

Performance > ReviewProcess > Schedules

Payloads

New Field competencies_assessments_configuration has been added
Configuration of the competencies assessments feature

Performance > ReviewProcess > Starts

Payloads

New Field competencies_assessments_configuration has been added
Configuration of the competencies assessments feature

Performance > ReviewProcess > Stops

Payloads

New Field competencies_assessments_configuration has been added
Configuration of the competencies assessments feature

Performance > ReviewProcess > Toggle archives

Payloads

New Field competencies_assessments_configuration has been added
Configuration of the competencies assessments feature

Performance > ReviewProcess > Update agreements configurations

Payloads

New Field competencies_assessments_configuration has been added
Configuration of the competencies assessments feature

Performance > ReviewProcess > Update basic infos

Payloads

New Field competencies_assessments_configuration has been added
Configuration of the competencies assessments feature

Performance > ReviewProcess > Update competencies assessments configurations

Payloads

New Field competencies_assessments_configuration has been added
Configuration of the competencies assessments feature

Performance > ReviewProcess > Update deadlines

Payloads

New Field competencies_assessments_configuration has been added
Configuration of the competencies assessments feature

Performance > ReviewProcess > Update employee score configurations

Payloads

New Field competencies_assessments_configuration has been added
Configuration of the competencies assessments feature

Performance > ReviewProcess > Update reviewer strategies

Payloads

New Field competencies_assessments_configuration has been added
Configuration of the competencies assessments feature

Performance > ReviewProcess > Update schedules

Payloads

New Field competencies_assessments_configuration has been added
Configuration of the competencies assessments feature

Performance > ReviewProcess > Update target strategies

Payloads

New Field competencies_assessments_configuration has been added
Configuration of the competencies assessments feature

We are happy to announce the new v2024-10-01 (Fibonacci) version has been released. This is the first versioned release of the v2 API. Most of the API remains the same, with updated endpoint paths.

As you know, our versions are named as famous numeric series. In mathematics, the Fibonacci sequence is a sequence in which each number is the sum of the two preceding ones.
The Fibonacci series has rapid growth, just like this version, which includes, among other things, the following changes:

The most relevant parts are Performance endpoints and webhooks, which are new in this version. Other additions are workplace information in EmployeeUpdates, Shift name information in ShiftManagement, as well as other improvements in Attendance, Expenses, Training, Tasks, and Project Management resources.

Don't miss out on the news it brings and read the detailed Changelog

In these last quarter, we have driven the Factorial's public API to first class. We have set the foundations for a fully stable and versioned public API. This means we have set the following changes:

Stabilizing version v2

V2 version has been in the oven for several months. Last July, we started to publish in v2 everything missing from v1. All the functionality in v1 must be now available in v2. If this is not the case, please contact us and let us know

We finally released v2 version at the beginning of September, deprecating v1 version

Versioned v2: 2024-10-01 and next

But we didn't stop here. Factorial's product teams move fast. They are constantly improving to deliver value to our clients. And the public API improves with them. Many of the new features are exposed to the public API, so our clients and developer partners can use them and bring more value to our users.

On the other hand, we know that public API consumers have their own pace. Keeping up to date with Factorial's API changes is probably not the first thing on their ToDO list.

This is why we are introducing API versioning in our v2 public API version. Every quarter, we are evolving our v2 version to new releases, without losing backwards compatibility within a year. This way, we give our API consumers enough time to adapt to new changes, while our product teams evolve fast.

Upgrading to newer versions should be must easy, just changing the paths most of the time. We will be publishing a detailed changelog, like 2024-10-01 Release Notes so clients and partners are able to easily upgrade.

Deprecating v1

Our v1 version has served us well for years, but it has several flaws and we need to move on. V1 version will keep working until April 1st, 2025. Afterward, it will be removed. Working webhooks will be automatically migrated to v2.

Attendance > Open shift

Reads all Open shifts

Request

Modified Field employee_id type has been changed to list of numbers and renamed to employee_ids - Employee ids to filter the open shifts by.

Employees > Employee

Updates an Employee

Request

New Field disability_percentage_cents has been added - officially certified level of disability granted by public administration for individuals with physical or mental impairments, expressed in cents

Response

New Field disability_percentage_cents has been added - officially certified level of disability granted by public administration for individuals with physical or mental impairments, expressed in cents

EmployeeUpdates > New hire

Response

New Field workplace_id has been added - workplace id of the employee.

EmployeeUpdates > Personal change

Response

New Field workplace_id has been added - workplace id of the employee.

Expenses > Expensable

Reads a single Expensable

Request

Modified Field group_id type has been changed to list of numbers and renamed to group_ids - __

Response

New Field per_diem has been added - __

Expenses > Mileage

Response

New Field round_trip has been added - Indicates if the mileage is a round trip

Performance > Agreement

Reads all Agreements

New Endpoint

Reads a single Agreement

New Endpoint

Bulk Initiates an Agreement

New Endpoint

Initiates an Agreement

New Endpoint

Response

New Field self_comments has been added - Self comments by question

New Field manager_comments has been added - Manager comments by question

New Field self_evaluation_id has been added - Self review evaluation ID

New Field manager_evaluation_id has been added - Manager review evaluation ID

Removed Field reviewer_access_id has been removed - __

Removed Field manager_questionnaire has been removed - __

Removed Field self_questionnaire has been removed - __

Performance > Review Evaluation

Reads all Review Evaluations

New Endpoint

Reads a single Review Evaluation

New Endpoint

Replace reviewers a Review evaluation

New Endpoint

Performance > Review Evaluations Answer

Reads all Review Evaluations Answer

New Endpoint

Performance > Review Owner

Reads all Review Owner

New Endpoint

Deletes a Review Owner

New Endpoint

Bulk creates a Review Owner

NewEndpoint

Performance > Review Processes

Reads all Review processes

New Endpoint

Reads a single Review process

New Endpoint

Creates a Review process

New Endpoint

Deletes a Review process

New Endpoint

Duplicates a Review process

New Endpoint

Remind in bulks a Review process

New Endpoint

Reopens a Review process

New Endpoint

Starts a Review process

New Endpoint

Stops a Review process

New Endpoint

Toggle archives a Review process

New Endpoint

Update agreements configurations a Review process

New Endpoint

Update basic infos a Review process

New Endpoint

Update deadlines a Review process

New Endpoint

Update reviewer strategies a Review process

New Endpoint

Update schedules a Review process

New Endpoint

Update target strategies a Review process

New Endpoint

Performance > Review Process Estimated Targets

Reads all Review process estimated targets

New Endpoint

Performance > Review Process Targets

Reads all Review process targets

New Endpoint

Reads a single Review process targets

New Endpoint

Deletes a Review process targets

New Endpoint

Add peers a Review process target

New Endpoint

Bulk creates a Review process target

New Endpoint

Remove peer evaluations a Review process target

New Endpoint

Performance > Review Questionnaire By Strategies

Reads all Review questionnaire by strategies

New Endpoint

Reads a single Review questionnaire by strategies

New Endpoint

Update default rating scales a Review questionnaire by strategies

New Endpoint

Update questionnaire for strategies a Review questionnaire by strategies

New Endpoint

Performance > Review Visibility Setting

Reads all Review visibility settings

New Endpoint

Updates a Review visibility setting

New Endpoint

ProjectManagement > Project

Reads a single Project

Request

New Field client_ids has been added - Retrieve only the projects that are related to the client passed in the request.

Response

New Field client_id has been added - The client id of the project

ProjectManagement > Project task

Bulk duplicates a Project task

Request

New Field exclude_assignees has been added - Set this to true if you want to exclude assignees from the duplicated tasks

New Field subproject_id has been added - Subproject id where the tasks will be duplicated

ProjectManagement > Project worker

Response

Removed Field labor_cost_currency has been removed - __

ShiftManagement > Shift

Reads a single Shift

Request

New Field name has been added - __

Response

New Field name has been added - Name of the shift

Tasks > Task

Reads a single Task

Request

New Field involvee_id has been added - retrieve tasks where the user is affectee or assignee

Timeoff > Allowance stat

Reads a single Allowance stat

Request

Modified Field reference_date is now mandatory - __

Trainings > Training

Reads a single Training

Request

New Field with_expired_memberships has been added - __

Creates a Training

Request

New Field objectives has been added - Objectives of the course

Response

New Field objectives has been added - Objectives of the course

New Field number_of_expired_participants has been added - Number of participants that have the course expired or about to expire in the next 3 months. Only applicable to trainings with validity period.

Trainings > Training membership

Response

Modified Field training_completion_date has been renamed to training_completed_at - This field is used to record the date a training was completed for trainings that have an expiry date.

Webhooks

Employees > Employee > Create with contracts

Payload

New Field disability_percentage_cents has been added - officially certified level of disability granted by public administration for individuals with physical or mental impairments, expressed in cents

Employees > Employee > Invites

Payload

New Field disability_percentage_cents has been added - officially certified level of disability granted by public administration for individuals with physical or mental impairments, expressed in cents

Employees > Employee > Terminates

Payload

New Field disability_percentage_cents has been added - officially certified level of disability granted by public administration for individuals with physical or mental impairments, expressed in cents

Employees > Employee > Unterminates

Payload

New Field disability_percentage_cents has been added - officially certified level of disability granted by public administration for individuals with physical or mental impairments, expressed in cents

Employees > Employee > Updates

Payload

New Field disability_percentage_cents has been added - officially certified level of disability granted by public administration for individuals with physical or mental impairments, expressed in cents

Performance > ReviewProcess > Creates

New Webhook

Performance > ReviewProcess > Deletes

New Webhook

Performance > ReviewProcess > Duplicates

New Webhook

Performance > ReviewProcess > Remind in bulks

New Webhook

Performance > ReviewProcess > Reopens

New Webhook

Performance > ReviewProcess > Starts

New Webhook

Performance > ReviewProcess > Stops

New Webhook

Performance > ReviewProcess > Toggle archives

New Webhook

Performance > ReviewProcess > Update agreements configurations

New Webhook

Performance > ReviewProcess > Update basic infos

New Webhook

Performance > ReviewProcess > Update schedules

New Webhook

Performance > ReviewProcess > Update target strategies

New Webhook

ShiftManagement > Shift > Bulk deletes

Payload

New Field name has been added - Name of the shift

ShiftManagement > Shift > Creates

Payload

New Field name has been added - Name of the shift

ShiftManagement > Shift > Deletes

Payload

New Field name has been added - Name of the shift

Trainings > Training > Bulk deletes

Payload

New Field objectives has been added - Objectives of the course

New Field number_of_expired_participants has been added - Number of participants that have the course expired or about to expire in the next 3 months. Only applicable to trainings with validity period.

Trainings > Training > Bulk update catalogs

Payload

New Field objectives has been added - Objectives of the course

New Field number_of_expired_participants has been added - Number of participants that have the course expired or about to expire in the next 3 months. Only applicable to trainings with validity period.

Trainings > Training > Creates

Payload

New Field objectives has been added - Objectives of the course

New Field number_of_expired_participants has been added - Number of participants that have the course expired or about to expire in the next 3 months. Only applicable to trainings with validity period.

Trainings > Training > Deletes

Payload

New Field objectives has been added - Objectives of the course

New Field number_of_expired_participants has been added - Number of participants that have the course expired or about to expire in the next 3 months. Only applicable to trainings with validity period.

Trainings > Training > Updates

Payload

New Field objectives has been added - Objectives of the course

New Field number_of_expired_participants has been added - Number of participants that have the course expired or about to expire in the next 3 months. Only applicable to trainings with validity period.

Trainings > Training > Update statuses

Payload

New Field objectives has been added - Objectives of the course

New Field number_of_expired_participants has been added - Number of participants that have the course expired or about to expire in the next 3 months. Only applicable to trainings with validity period.

Since today, we have enabled webhooks to subscribe to events that take place in Factorial. You can check the webhooks API documentation here.

Right now we just have a trigger, which calls you when an employee is invited to your company.

Be sure to check this documentation since we plan to launch more webhooks in the near future!

Welcome to the developer hub and documentation for factorial! We just launched the first version of our public API.

The Factorial API is organized around REST. Our API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

Make sure to regularly check the changelog, as we will be continuously improving the Factorial API, always keeping in mind retro compatibility through versioning.

To start using the API head over to our Getting Started guide.