Payroll integrations

This guide is for partners connecting an external payroll software to Factorial.

Clients manage people data in Factorial (hires, terminations, contract conditions, absences, variable pay) and push each of those changes into the payroll software. Factorial acts as the single source of truth for payroll input. After calculation happens at the payroll engine, results and paylips are pulled back to Factorial.

A payroll integration typically covers five things:

Area	What it covers
Employee life cycle	New hires, terminations, contract changes, personal data changes
Absences	Leaves that affect the payroll run (sick leave, parental leave, unpaid leave…)
Payroll variables	Compensations and supplements for the period: bonuses, overtime, commissions, benefits in kind, deductions
Payroll variables results	The calculation result from the bookkeeper on compensations and supplements that will actually be paid to employees
Payroll output	Payslips and any document generated by the payroll engine, imported back into Factorial

📘
This guide builds on the Integrations Framework. Read it first: it describes the setup, the sync run lifecycle and the status reporting contract that every case below relies on.
After the integrations framework is setup, you can cover each of these cases

New hires

Direction: outbound. The client creates the employee in Factorial (manually, by import, or from the ATS module) and syncs / exports it to the payroll software.

What you receive: A syncable state item per new hire, with:

sync_type: employee_updates/new_hire
syncable_resource: employees/employee
syncable_id: the employee id

Related Endpoints

Reads all Employees syncable_resource — names, identifiers, date of birth, gender, nationality, address, bank account, etc.
Reads all Reference contracts — the contract conditions that apply today: start and end dates, salary amount and frequency, etc.
Reads all Contract versions — the full version history, when the effective date matters
Reads all Legal entities — the payroll account the employee belongs to, and its country
Reads all Identifiers — country-specific statutory identifiers (tax id) for Portugal, Italy and Germany
Reads all Tree nodes — job catalog role and level for the job position
Reads all Cost centers — when payroll splits cost by center

📘
If hires originate from the external payroll software instead, use the inbound direction to sync them to Factorial.

Terminations

Direction: outbound. The client terminates the employee in Factorial with a date and a reason

What you receive: A syncable state item per termination, with:

sync_type: employee_updates/termination
syncable_resource: employees/employee
syncable_id: the employee id

Related Endpoints

Reads all Employees syncable_resource — terminated_on, termination_reason, termination_reason_type and termination_type_description
Reads all Reference contracts — the contract end date, when it differs from the termination date
Reads all Legal entities — the payroll account and its country, since reasons are country-specific

📘
If terminations originate in your system, Terminates an Employee and Unterminates an Employee write them into Factorial.

Contract changes

Direction: outbound. The client updates the conditions of the agreement in Factorial and syncs. Apply the change in payroll software with the right effective date.

What you receive: A syncable state item per contract change, with:

sync_type: employee_updates/contract_change
syncable_resource: contracts/contract_version
syncable_id: the contract version id

Related Endpoints

Reads all Contract versions syncable_resource — the version being synced: effective date, start and end dates, salary amount and frequency, working hours and week days
Reads all Reference contracts — the version that applies today, to compare against
Reads all Compensations — fixed compensations attached to the contract
Reads all Tree nodes — job catalog role and level when the change touches the job position
Reads all Legal entities — the country, since contract attributes are country-specific

Personal data changes

Direction: outbound. The employee updates their profile in Factorial.

What you receive: A syncable state item per change, with:

sync_type: one per kind of change, so you can support only the ones your engine needs — employee_updates/personal_change_id, _name, _bank, _address, _gender, _nationality, _email, _phone_number, _irpf, _health_insurance, _residence, _workplace, _birth_name, _academic_title, _country_of_birth, _place_of_birth, _permits_and_certificates, _taxes_and_deductions, _work_activity
syncable_resource: employees/employee
syncable_id: the employee id

Related Endpoints

Reads all Employees syncable_resource — the current state of the profile after the change
Reads all Identifiers — country-specific statutory identifiers, when the change touches the tax id
Reads all Legal entities — the payroll account and its country

Absences

Direction: outbound. The employee requests time off in Factorial and the manager approves it. The user syncs the approved absences that need to be registered in the external payroll software.

What you receive: A syncable state item per absence, with:

sync_type: employee_updates/leave
syncable_resource: timeoff/leave
syncable_id: the leave id

Unlike the other cases, the payload is rich: leave type (id, name, code, workable), start and finish dates, half day and hourly indicators, days taken, hours used and workable by date, contract working hours, frequency and week days, plus the employee and legal entity codes.

Related Endpoints

Reads all Leaves syncable_resource — the leaves themselves, with their current state. Pass include_duration_by_day=true to get the per-day breakdown of workable and used units in duration_by_day_attributes
Reads all Leave types — the client's leave catalogue, for mapping
Reads all French leave day counts — the French décompte des congés: forfait jours, RTT and congés payés forced to days, JNT cap applied, and ouvrés / ouvrables / calendaires resolved from the work schedule
Reads all Employees — to resolve the employee behind the leave
Reads all Legal entities — the payroll account the absence belongs to

Payroll variables

Direction: outbound. The client defines the compensations for the period in Factorial and syncs the whole period at once.

What you receive: A syncable state item per compensation, with:

sync_type: compensations/compensation
syncable_resource: compensations/payroll_run_employees_compensation
syncable_id: the compensation id

The payload carries employee_id, payroll_concept_id, amount, unit, effective_on, legal_entity_id, plus the employee, payroll concept, legal entity and workplace codes.

Amounts are integers: cents for money, minutes for time, km for distance, units for unit. effective_on is typically the last day of the payroll run.

Related Endpoints

Reads all Employee compensations syncable_resource — the compensations for the payroll run
Reads all Payroll runs — the batch that compensates a set of employees for a period
Reads all Concepts — the concept catalogue behind payroll_concept_id

Payroll variables results

Direction: inbound. Once the bookkeeper closes the payroll run, push the calculation results — the compensations and supplements that will actually be paid to each employee — back into Factorial so the client has a full record alongside the payslips.

What you send. One record per employee per payroll period, carrying the breakdown of earnings, deductions and net pay as computed by the payroll engine. The write is atomic — everything is validated before anything is persisted, so a 4xx/5xx means nothing was written and the batch can be retried as is. Re-posting an (employee, concept) pair replaces the amount and keeps the row id; pairs you don't send are left untouched (there's no delete). For larger payrolls, send chunks of 1,000 amounts or fewer, keeping each employee's items together in the same request.

Related Endpoints

Creates Payroll results in bulk — body is payroll_run_id plus results: [{employee_id, items: [{payroll_concept_id, amount}]}]; Factorial ids only, amounts are signed integers in the concept's minor unit (cents for money). Requires the compensations scope and the "Import payroll results" permission
Reads all Payroll runs — resolve the payroll_run_id to write results against
Reads all Employee compensations — the compensations of the payroll run to write results against
Reads all Employees — resolve employees by company_identifier before writing
Reads all Concepts — match your concept codes to Factorial's payroll_concept_id

Payslips

Direction: inbound. The payroll engine produces the payslip, the document that reflect the payment for the employee in a given payroll period. These documents are distributed inside Factorial.

Once a payroll run is closed, fetch the payslips from your software and upload one document per employee into Factorial, filed in the employee's Payslip folder.

Related Endpoints

Reads all Folders — locate the employee's payslip folder
Creates a Document
Updates a Document — replace a payslip after a correction

We're excited to see the integration you build! 🚀