GuidesAPI ReferenceChangelog
Changelog
Start typing to search…
These docs are for v2025-04-01. Click to read the latest docs for v2026-01-01.
Back to All
Added

Introducing the Job Catalog Tree

1 day ago by Antonio Tapiador

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 API Endpoints in use:
  • 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.

Step 1: Identify the Correct Level

  1. **Access the Job Catalog endpoint ** to retrieve all roles.
  2. Select the desired role (e.g., “Engineering”).
  3. 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.
  4. 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.

Step 2: Create a New Employee with Contract

  1. Use the Employees > Employee endpoint to create the employee record.
  2. 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.
  3. Factorial will automatically assign the corresponding role based on the level.

Step 3: Add or Update a Contract Version

  1. Use the Contracts > ContractVersion > Updates endpoint to create a new contract version for an existing employee.
  2. Specify the start date and the job catalog level identified in Step 1. This uuid must be informed in job_catalog_tree_node_uuid.
  3. 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.