This behavior has been fixed in the 2026-01-01 Release , normalizing the response and removing the fiels from this endpoint. It will now include the resource_id field from the CustomResources > Resource endpoint.
With the resource_id field, it is possible to navigate and fetch all the values:
The Job Catalog Tree is a new powerful feature in Factorial, that allows organizations to flexibly describe their job positions and roles. This new feature also demands new API endpoints
The key change is the transition from using the deprecated job_catalog_level_id to the newjob_catalog_tree_node_uuid when creating or updating employee contracts. This change ensures that all role and level assignments leverage the hierarchical catalog structure, maintaining consistency and accuracy across all employee records.
Current Situation
During the creation or update of employee contracts, the existing integration uses the job_catalog_level_id parameter to assign a level to an employee's contract version. This ID is retrieved from the legacy Job Catalog Levels and Roles endpoints.
Legacy Contract API in use: The employee/contract creation/update endpoints currently accept job_catalog_level_id. For more information on the contract API, refer to:
POST /api/2025-10-01/resources/contracts/contract-versions (and related employee/contract creation endpoints) Contracts > ContractVersion
Once the migration has been performed, the legacy job_catalog_level_id should not be used, and it is planned to be deprecated in the next version of the API.
End situation
… after migration to the new JobCatalog tree.
Purpose - Ensure employees are correctly assigned a role and level in their contracts using Factorial’s job catalog, without storing any catalog information locally.
Retrieve all levels under that role from the catalog. It’s necessary to call the endpoint twice to get the role and then all the levels under that role, to pick the selected one.
Choose the specific level required for the employee (e.g., “Senior Engineer 1”).
The key point: every time a contract is created or updated, this lookup is done live. No catalog information should be stored in the third party system.
Include contract details such as start date, salary, and the job catalog level identified in Step 1. This uuid must be informed in job_catalog_tree_node_uuid.
Factorial will automatically assign the corresponding role based on the level.
Specify the start date and the job catalog level identified in Step 1. This uuid must be informed in job_catalog_tree_node_uuid.
Factorial will derive the employee’s role from the level and apply it to the contract version.
Important Note on Role Assignment
In the previous Job Catalog structure, it was possible to assign a Role to a contract by using a hidden default level associated with that role.
With the migration to the new Job Catalog Tree, this is no longer possible. The new structure requires explicitly selecting a Level (the leaf node in the tree structure) and assigning its job_catalog_tree_node_uuid to the contract. The parent Role will be automatically derived from this assigned level. You must only assign a level UUID, not a role UUID, to the contract.
Key Rules
Always query the Job Catalog to get the current roles and levels; never store this information locally.
Always assign a level via the job catalog level identifier; the role is automatically derived.
Ensure contract dates and details are accurate before sending to Factorial.
Verify after creation that the employee’s contract reflects the correct level and role.
This workflow guarantees accurate role and level assignment, maintains consistency across contracts, and keeps all catalog information centralized in Factorial.
We are happy to announce the new v2026-01-01 (Lambert) version has been released.
As you know, our versions are named after famous numeric series. In mathematics, a Lambert series is a type of generating function that connects arithmetic sequences with infinite sums, revealing hidden structure and relationships between numbers.
The Lambert series is known for how small inputs can unfold into rich and powerful results, much like this version.
Breaking changes
The two most important changes in this new version are:
The v2026-01-01 release adds several new endpoints across modules like:
IT Management assets and models
Procurement purchase orders, requests and types.
Project Management planned records and subproject updates
Finance budget options
Plus new capabilities like setting regular access start dates for employees and toggling a shift’s clock into/out of breaks.
It also expands many existing resources with new request and response fields, notably cost centers, projects, budgets on expenses, update timestamps for custom fields, and extra leave, training fields (with corresponding webhook payload updates).
New Field job_catalog_tree_node_uuid has been added
The uuid node in the job catalog tree. for now it only supports level nodes. from this point in the job catalog tree you can get the full ancestor path to the root node including the role. refer to job_catalog/tree_nodes endpoint.
New Field job_catalog_tree_node_uuid has been added
The uuid node in the job catalog tree. for now it only supports level nodes. from this point in the job catalog tree you can get the full ancestor path to the root node including the role. refer to job_catalog/tree_nodes endpoint.
New Field job_catalog_tree_node_uuids has been added
The uuid of nodes in the job catalog tree. as only level nodes are accepted and persisted, so filtering with other node types will return no results. refer to job_catalog/tree_nodes endpoint.
All Responses
New Field is_reference has been added
Whether it is the reference contract today or not. it is important to remark that reference contract doesn't mean active
New Field job_catalog_tree_node_uuid has been added
The uuid node in the job catalog tree. for now it only supports level nodes. from this point in the job catalog tree you can get the full ancestor path to the root node including the role. refer to job_catalog/tree_nodes endpoint.
Contracts > Contract version history
Contracts contract version history
All Responses
New Field job_catalog_tree_node_uuid has been added
The uuid node in the job catalog tree. for now it only supports level nodes. from this point in the job catalog tree you can get the full ancestor path to the root node including the role. refer to job_catalog/tree_nodes endpoint.
New Field job_catalog_tree_node_uuids has been added
The uuid of nodes in the job catalog tree.
All Responses
New Field is_reference has been added
Whether it is the reference contract today or not. it is important to remark that reference contract doesn't mean active
New Field job_catalog_tree_node_uuid has been added
The uuid node in the job catalog tree. for now it only supports level nodes. from this point in the job catalog tree you can get the full ancestor path to the root node including the role. refer to job_catalog/tree_nodes endpoint.
New Field job_catalog_tree_node_uuid has been added
The uuid of nodes in the job catalog tree. for now it only supports level nodes. from this point in the job catalog tree you can get the full ancestor path to the root node including the role. refer to job_catalog/tree_nodes endpoint.
Integrations SyncableItem represents the item data that needs to be synced within a SyncRun. A SyncRun represents each synchronization execution of a set of items. This endpoint is designed to be used by integrators building a integration between Factorial and an external systems.
All Responses
New Field syncable_type has been added
Type of the syncable item
New Field is_reference has been added
Whether it is the reference contract today or not. it is important to remark that reference contract doesn't mean active
New Field job_catalog_tree_node_uuid has been added
The uuid node in the job catalog tree. for now it only supports level nodes. from this point in the job catalog tree you can get the full ancestor path to the root node including the role. refer to job_catalog/tree_nodes endpoint.
New Field is_reference has been added
Whether it is the reference contract today or not. it is important to remark that reference contract doesn't mean active
New Field job_catalog_tree_node_uuid has been added
The uuid node in the job catalog tree. for now it only supports level nodes. from this point in the job catalog tree you can get the full ancestor path to the root node including the role. refer to job_catalog/tree_nodes endpoint.
New Field is_reference has been added
Whether it is the reference contract today or not. it is important to remark that reference contract doesn't mean active
New Field job_catalog_tree_node_uuid has been added
The uuid node in the job catalog tree. for now it only supports level nodes. from this point in the job catalog tree you can get the full ancestor path to the root node including the role. refer to job_catalog/tree_nodes endpoint.
We are excited to introduce v2025-10-01 (Dirichlet)
of our API! This version continues our commitment to evolving the platform without introducing breaking changes, offering new capabilities and enhancements across key business areas.
Inspired by the Dirichlet series—known for their rigor and role as a bridge toward deeper mathematical insights—this update strengthens and extends the API’s functionality, providing your integrations with more precision, control, and reliability.
This release introduces impactful additions across Attendance, Banking, Contracts, Custom Resources, Expenses, Finance, Performance, Project Management, Shift Management, Time Off, Trainings, and Webhooks. You’ll find powerful new endpoints, expanded request and response fields, and enriched payloads designed to make your automation and reporting more complete and adaptable.
Some highlights include:
Attendance Reviews → new endpoints for bulk create, bulk destroy, and list reviews, plus the new id field in responses.
Bank Accounts → new field bank_account_membership_employee_ids and removal of bank_account_membership_access_ids.
Contracts → expanded support with new fields like job_catalog_role_id and archived filters across French, German, and Portuguese contract types.
Custom Resources → new endpoints and fields such as attachable_id for more flexible resource handling.
Expenses → bulk set-to-paid endpoint for expensables.
Finance → richer Contact data, now including email, website, and phone_number in create, update, read, and responses.
Performance → new endpoints for evaluation scores, updated filters (reviewer_strategies), and field removals for clarity.
Project Management → include_costs option when reading projects.
Shift Management → bulk create with new planned_breaks field.
Time Off → new duration_attributes field for leaves, also reflected in webhook payloads.
Trainings → session endpoints enhanced with the active filter.
Webhooks → enriched payloads for Contracts (Contract Versions) and Time Off (Leaves), including new job_catalog_role_id and duration_attributes fields.
Check out the full Changelog to explore every new feature and improvement.
We’d love to hear how these updates help you build smarter, faster, and more scalable integrations!
New Field location_ids has been added
Location ids
Removed Field location_id has been removed
New Field team_ids has been added
Team ids
Removed Field team_id has been removed
New Field employee_ids has been added
Filter by the default location of these employees
Integrations > Syncable item
Integrations SyncableItem represents the item data that needs to be synced within a SyncRun. A SyncRun represents each synchronization execution of a set of items. This endpoint is designed to be used by integrators building a integration between Factorial and an external systems.
Integrations SyncableSyncRun represents a synchronization execution of a SyncableItem within a sync run. A sync run represents each synchronization execution of a set of items. This endpoint is designed to be used by integrators building a integration between Factorial and an external systems.
New Field include_costs has been added
If true we will perform the costs calculations and will be return the total cost. if false, 0 will be returned and no costs calculations will be performed.
New Field client_ids has been added
Retrieve only the projects that are related to the clients passed in the request, refers to finance/contacts.
We are excited to introduce v2025-07-01 (Laurent) of our API! This version continues our commitment to evolving the platform without introducing breaking changes, offering new capabilities and enhancements across key business areas.
Inspired by the Laurent series—which extends Taylor series to represent functions more flexibly—this update broadens and deepens the API’s functionality, giving your integrations greater range and precision.
This release brings impactful additions to Performance, Contracts, and Trainings, along with updates to Attendance, Finance, Employees, ATS, Banking, and more. You’ll find powerful new endpoints, expanded request and response fields, and enriched webhook payloads designed to make your automation and reporting more complete and adaptable.
Some highlights include:
New endpoints for Contract Versions, Spanish Working Day Types, Training Classes, and Banking Transactions.
Richer Employee data, including birthplace, country of birth, and attendance eligibility.
Advanced Performance Review configurations, with simplified payloads and custom templates.
Greater control in Time Planning, ATS, and Project Management, with new filters, fields, and scheduling options.
Extended Financial data fields, enhancing the traceability of documents and cost centers.
Check out the full Changelog to explore every new feature and improvement.
We’d love to hear how these updates help you build smarter, faster, and more scalable integrations!
We are excited to introduce v2025-04-01 (Taylor) of our API! This version brings a wide range of enhancements, making our API more powerful and adaptable without breaking changes.
Just like the Taylor series approximates complex functions by breaking them down into simpler polynomial terms, this API update refines and extends existing functionalities, making your integrations more precise and efficient with incremental but impactful changes.
The most significant enhancements focus on Contracts, Finance, and Employee endpoints and webhooks, while other key areas, including ATS, Attendance, Banking, Performance, and Project Management, also benefit from new endpoints and expanded field options.
Check out the full Changelog for a deeper dive into all the new features and enhancements.
Let us know how you leverage these updates to improve your processes!
New Field annual_working_time_distribution has been added Allows companies to define how annual working hours are spread across the year to ensure compliance with legal limits.
New Field annual_working_time_distribution has been added Allows companies to define how annual working hours are spread across the year to ensure compliance with legal limits.
All Responses
New Field annual_working_time_distribution has been added Allows companies to define how annual working hours are spread across the year to ensure compliance with legal limits.
Contracts > Reference contract
Contracts reference contract
All Responses
New Field annual_working_time_distribution has been added Allows companies to define how annual working hours are spread across the year to ensure compliance with legal limits.
New Field schedule has been added Scheduled or self paced. scheduled needs to have a start time and end time within the same day, self paced can start and end in different days and specific time won't be shown in the frontend app.
New Field schedule has been added Scheduled or self paced. scheduled needs to have a start time and end time within the same day, self paced can start and end in different days and specific time won't be shown in the frontend app.
All Responses
Removed Field session_attendances_status has been removed
New Field schedule has been added Session schedule information (scheduled, self-paced)
New Field parent_id has been added Id of the recurrent session that is parent of the current one
New Field annual_working_time_distribution has been added Allows companies to define how annual working hours are spread across the year to ensure compliance with legal limits.
New Field annual_working_time_distribution has been added Allows companies to define how annual working hours are spread across the year to ensure compliance with legal limits.
New Field annual_working_time_distribution has been added Allows companies to define how annual working hours are spread across the year to ensure compliance with legal limits.
