Employee Updates

Usage

Fetch employee lifecycle events (new hires, terminations, absences):

import asyncio
import factorialhr

async def main():
    auth = factorialhr.AccessTokenAuth("your_access_token")
    async with factorialhr.ApiClient(auth=auth) as api:
        absences = factorialhr.AbsencesEndpoint(api)
        for a in (await absences.all()).data():
            print(a.employee_id, a.starts_on, a.ends_on)
        terminations = factorialhr.TerminationsEndpoint(api)
        response = await terminations.get(params={"limit": 10})
        for t in response.data():
            print(t.employee_id, t.termination_date)

asyncio.run(main())

class factorialhr.AbsencesEndpoint(api: ApiClient)[source]

Endpoint for employee_updates/absences operations.

async all(**kwargs) → ListApiResponse[EmployeeAbsence][source]

Get all absences records.

Official documentation: employee_updates/absences

Parameters:: kwargs (optional) – Optional keyword arguments (e.g. params for query string) forwarded to the HTTP request.
Raises:: httpx.HTTPStatusError – When the API returns an error status code.
Returns:: Response containing the list of records.
Return type:: ListApiResponse[EmployeeAbsence]

async get(**kwargs) → MetaApiResponse[EmployeeAbsence][source]

Get absences with pagination metadata.

Official documentation: employee_updates/absences

Parameters:: kwargs (optional) – Optional keyword arguments (e.g. params for query string) forwarded to the HTTP request.
Raises:: httpx.HTTPStatusError – When the API returns an error status code.
Returns:: Response containing records and pagination metadata.
Return type:: MetaApiResponse[EmployeeAbsence]

async get_by_id(absence_id: int | str, **kwargs) → EmployeeAbsence[source]

Get a specific absence by ID.

Official documentation: employee_updates/absences

Parameters:

absence_id (int | str) – The unique identifier.
kwargs (optional) – Optional keyword arguments (e.g. params for query string) forwarded to the HTTP request.

Raises:

httpx.HTTPStatusError – When the API returns an error status code.

Returns:

The record.

Return type:

EmployeeAbsence

class factorialhr.ContractChangesEndpoint(api: ApiClient)[source]

Endpoint for employee_updates/contract_changes operations.

async all(**kwargs) → ListApiResponse[EmployeeContractChange][source]

Get all contract changes records.

Official documentation: employee_updates/contract_changes

Parameters:: kwargs (optional) – Optional keyword arguments (e.g. params for query string) forwarded to the HTTP request.
Raises:: httpx.HTTPStatusError – When the API returns an error status code.
Returns:: Response containing the list of records.
Return type:: ListApiResponse[EmployeeContractChange]

async get(**kwargs) → MetaApiResponse[EmployeeContractChange][source]

Get contract changes with pagination metadata.

Official documentation: employee_updates/contract_changes

Parameters:: kwargs (optional) – Optional keyword arguments (e.g. params for query string) forwarded to the HTTP request.
Raises:: httpx.HTTPStatusError – When the API returns an error status code.
Returns:: Response containing records and pagination metadata.
Return type:: MetaApiResponse[EmployeeContractChange]

async get_by_id(contract_change_id: int | str, **kwargs) → EmployeeContractChange[source]

Get a specific contract change by ID.

Official documentation: employee_updates/contract_changes

Parameters:

contract_change_id (int | str) – The unique identifier.
kwargs (optional) – Optional keyword arguments (e.g. params for query string) forwarded to the HTTP request.

Raises:

httpx.HTTPStatusError – When the API returns an error status code.

Returns:

The record.

Return type:

EmployeeContractChange

Model for employee_updates_absence.

approved: bool | None: Indicates if the absence is approved

description: str | None: A description of the absence

employee_full_name: str | None: Full name of the employee

employee_id: int | None: Employee id of the absence

finish_on: datetime | None: The end date of the absence

half_day: str | None: Indicates if the absence is taken as a half-day

hours_amount_in_cents: int | None: The total number of hours taken for the absence, represented in cents

id: int: Identifier of the absence employee update

leave_type_id: int | None: The id of the leave type

leave_type_name: str | None: The name of the leave type

prev_finish_on: str | None: The previous end date of the absence

prev_start_on: datetime | None: The previous start date of the absence

start_on: datetime | None: The start date of the absence

status: str: The status of the employee update

class factorialhr.EmployeeContractChange(*, id: int, status: str, effective_on: date, starts_on: date | None = None, ends_on: date | None = None, employee_id: int, job_title: str | None = None, job_role: str | None = None, job_level: str | None = None, has_payroll: bool, salary_amount: int | None = None, salary_frequency: str | None = None, working_week_days: str | None = None, working_hours: int | None = None, working_hours_frequency: str | None = None, country: str | None = None, es_has_teleworking_contract: bool | None = None, es_cotization_group: int | None = None, es_contract_observations: str | None = None, es_job_description: str | None = None, es_contract_type_id: int | None = None, es_contract_type_name: str | None = None, es_trial_period_ends_on: date | None = None, es_working_day_type_id: int | None = None, es_education_level_id: int | None = None, es_professional_category_id: int | None = None, fr_employee_type: str | None = None, fr_forfait_jours: bool, fr_jours_par_an: int | None = None, fr_coefficient: str | None = None, fr_level_id: int | None = None, fr_level_name: str | None = None, fr_step_id: int | None = None, fr_step_name: str | None = None, fr_mutual_id: int | None = None, fr_mutual_name: str | None = None, fr_professional_category_id: int | None = None, fr_professional_category_name: str | None = None, fr_work_type_id: int | None = None, fr_work_type_name: str | None = None, compensation_ids: Sequence[int] | None = None, fr_contract_type_id: int | None = None, fr_contract_type_name: str | None = None, de_contract_type_id: int | None = None, de_contract_type_name: str | None = None, pt_contract_type_id: int | None = None, pt_contract_type_name: str | None = None, created_at: datetime, updated_at: datetime)[source]

Model for employee_updates_contract_change.

compensation_ids: Sequence[int] | None: List of compensation identifiers

country: str | None: The country on the contract change

created_at: datetime: Creation timestamp of the contract change

de_contract_type_id: int | None: The contract type id on the contract change

de_contract_type_name: str | None: The contract type name on the contract change

effective_on: date: The effective date of the contract

employee_id: int: The employee id

ends_on: date | None: The end date of the contract

es_contract_observations: str | None: The contract observations on the contract change

es_contract_type_id: int | None: The contract type id on the contract change

es_contract_type_name: str | None: The contract type name on the contract change

es_cotization_group: int | None: The cotization group on the contract change

es_education_level_id: int | None: The education level id on the contract change

es_has_teleworking_contract: bool | None: The teleworking status on the contract change

es_job_description: str | None: The job description on the contract change

es_professional_category_id: int | None: The professional category id on the contract change

es_trial_period_ends_on: date | None: The trial period end date on the contract change

es_working_day_type_id: int | None: The working day type id on the contract change

fr_coefficient: str | None: The coefficient on the contract change

fr_contract_type_id: int | None: The contract type id on the contract change

fr_contract_type_name: str | None: The contract type name on the contract change

fr_employee_type: str | None: The employee type on the contract change

fr_forfait_jours: bool: The forfait jours status on the contract change

fr_jours_par_an: int | None: The jours par an on the contract change

fr_level_id: int | None: The level id on the contract change

fr_level_name: str | None: The level name on the contract change

fr_mutual_id: int | None: The mutual id on the contract change

fr_mutual_name: str | None: The mutual name on the contract change

fr_professional_category_id: int | None: The professional category id on the contract change

fr_professional_category_name: str | None: The professional category name on the contract change

fr_step_id: int | None: The step id on the contract change

fr_step_name: str | None: The step name on the contract change

fr_work_type_id: int | None: The work type id on the contract change

fr_work_type_name: str | None: The work type name on the contract change

has_payroll: bool: The payrollable status of the employee on the contract change

id: int: The id of the contract change incidence

job_level: str | None: The job level on the contract change

job_role: str | None: The job role on the contract change

job_title: str | None: The job title on the contract change

pt_contract_type_id: int | None: The contract type id on the contract change

pt_contract_type_name: str | None: The contract type name on the contract change

salary_amount: int | None: The salary amount on the contract change

salary_frequency: str | None: The salary payment frequency on the contract change

starts_on: date | None: The start date of the contract

status: str: The status of the contract change incidence

updated_at: datetime: Last update timestamp of the contract change

working_hours: int | None: The working hours on the contract change

working_hours_frequency: str | None: The working hours frequency on the contract change

working_week_days: str | None: The working week days on the contract change

Model for employee_updates_new_hire.

address: str: Address of the employee

bank_account: str | None: Bank account number of the employee

birth_name: str | None: The birth name of the new hire

city: str | None: City of the employee

contract_effective_date: date | None: Contract effective date

contract_end_date: date | None: Contract end date

country: str | None: Country code of the employee (Spain ES, United Kingdom GB)

date_of_birth: date | None: Birthday of the employee

employee_id: int: The employee id of the new hire

first_name: str: Name of the employee

gender: str | None: Gender of the employee (male | female)

id: int: The id of the new hire incidence

identifier: str | None: National identifier number

identifier_type: str | None: Type of identifier (ex passport)

job_title: str | None: Job title of the employee

last_name: str: Last name of the employee

legal_entity_id: int | None: The legal entity id of the new hire

manager_id: int | None: Manager id of the employee, you can get the manager id from employees endpoint

nationality: str | None: Nationality country code of the employee (Spain ES, United Kingdom GB)

payroll_identifier: str | None: Payroll identifier

phone_number: str | None: Phone number of the employee

postal_code: str | None: Postal code of the employee

salary_amount_in_cents: int | None: Salary amount in cents

salary_frequency: str | None: Salary payment frequency

social_security_number: str | None: Social security number of the employee

start_date: date | None: Start date of the employee

state: str | None: State/province/region of the employee

status: str: The status of the new hire incidence

tax_id: str | None: Tax identification number

work_email: str | None: Personal email of the employee

working_hours: int | None: Working hours

working_hours_frequency: str | None: Working hours frequency

workplace_id: int | None: Workplace id of the employee

Model for employee_updates_personal_change.

address_line_1: str | None: Address line 1 of the employee

address_line_2: str | None: Address line 2 of the employee

bank_number: str | None: Bank account number of the employee

city: str | None: City of the employee

country: str | None: Country code of the employee (Spain ES, United Kingdom GB)

date_of_birth: date | None: Birthday of the employee

employee_id: int: The employee id of the personal change

first_name: str: Name of the employee

gender: str | None: Gender of the employee (male | female)

id: int: The id of the personal change incidence

identifier: str | None: National identifier number

identifier_type: str | None: Type of identifier (ex passport)

job_title: str | None: Job title of the employee

last_name: str: Last name of the employee

nationality: str | None: Nationality country code of the employee (Spain ES, United Kingdom GB)

phone_number: str | None: Phone number of the employee

postal_code: str | None: Postal code of the employee

social_security_number: str | None: Social security number of the employee

state: str | None: State/province/region of the employee

status: str: The status of the personal change incidence

tax_id: str | None: Tax identification number

work_email: str | None: Personal email of the employee

workplace_id: int | None: Workplace id of the employee

class factorialhr.EmployeeSummary(*, id: int, employee_id: int | None = None, legal_entity_id: int, status: str, type: str, starts_on: date | None = None, ends_on: date | None = None, created_at: datetime)[source]

Model for employee_updates_summary.

created_at: datetime: Creation timestamp of the update

employee_id: int | None: Employee identifier

ends_on: date | None: End date of the update

id: int: Unique identifier for the employee update summary

legal_entity_id: int: Legal entity identifier

starts_on: date | None: Start date of the update

status: str: Status of the employee update

type: str: Type of employee update

class factorialhr.EmployeeTermination(*, id: int, status: str, employee_id: int, terminated_on: date | None = None, termination_reason: str | None = None, termination_observations: str | None = None, legal_entity_id: int | None = None, remaining_holidays: Sequence[Any], termination_reason_type: str | None = None, termination_type_description: str | None = None)[source]

Model for employee_updates_termination.

employee_id: int: Employee identifier

id: int: Unique identifier for the termination update

legal_entity_id: int | None: Legal entity identifier

remaining_holidays: Sequence[Any]: List of remaining holidays

status: str: Status of the termination update

terminated_on: date | None: Termination date

termination_observations: str | None: Observations about the termination

termination_reason: str | None: Reason for termination

termination_reason_type: str | None: Type of termination reason

termination_type_description: str | None: The description of the termination type

class factorialhr.EmployeeUpdatesEndpoint(api: ApiClient)[source]

Endpoint for employee_updates operations.

async all(**kwargs) → ListApiResponse[EmployeeAbsence][source]

Get all employee_updates records.

Official documentation: employee_updates

Parameters:: kwargs (optional) – Optional keyword arguments (e.g. params for query string) forwarded to the HTTP request.
Raises:: httpx.HTTPStatusError – When the API returns an error status code.
Returns:: Response containing the list of records.
Return type:: ListApiResponse[EmployeeAbsence]

async create(data: Mapping[str, Any], **kwargs) → EmployeeAbsence[source]

Create a new employee_updates.

Official documentation: employee_updates

Parameters:

data (Mapping[str, Any]) – Payload for the new record (key-value mapping).
kwargs (optional) – Optional keyword arguments (e.g. params for query string) forwarded to the HTTP request.

Raises:

httpx.HTTPStatusError – When the API returns an error status code.

Returns:

The created record.

Return type:

EmployeeAbsence

async delete(update_id: int | str, **kwargs) → None[source]

Delete a employee_updates.

Official documentation: employee_updates

Parameters:

update_id (int | str) – The unique identifier of the record to delete.
kwargs (optional) – Optional keyword arguments (e.g. params for query string) forwarded to the HTTP request.

Raises:

httpx.HTTPStatusError – When the API returns an error status code.

Returns:

None.

Return type:

None

async get(**kwargs) → MetaApiResponse[EmployeeAbsence][source]

Get employee_updates with pagination metadata.

Official documentation: employee_updates

Parameters:: kwargs (optional) – Optional keyword arguments (e.g. params for query string) forwarded to the HTTP request.
Raises:: httpx.HTTPStatusError – When the API returns an error status code.
Returns:: Response containing records and pagination metadata.
Return type:: MetaApiResponse[EmployeeAbsence]

async get_by_id(employee_update_id: int | str, **kwargs) → EmployeeAbsence[source]

Get a specific employee_updates by ID.

Official documentation: employee_updates

Parameters:

employee_update_id (int | str) – The unique identifier.
kwargs (optional) – Optional keyword arguments (e.g. params for query string) forwarded to the HTTP request.

Raises:

httpx.HTTPStatusError – When the API returns an error status code.

Returns:

The record.

Return type:

EmployeeAbsence

async update(update_id: int | str, data: Mapping[str, Any], **kwargs) → EmployeeAbsence[source]

Update a employee_updates.

Official documentation: employee_updates

Parameters:

update_id (int | str) – The unique identifier of the record to update.
data (Mapping[str, Any]) – Payload with fields to update (key-value mapping).
kwargs (optional) – Optional keyword arguments (e.g. params for query string) forwarded to the HTTP request.

Raises:

httpx.HTTPStatusError – When the API returns an error status code.

Returns:

The updated record.

Return type:

EmployeeAbsence

class factorialhr.NewHiresEndpoint(api: ApiClient)[source]

Endpoint for employee_updates/new_hires operations.

async all(**kwargs) → ListApiResponse[EmployeeNewHire][source]

Get all new hires records.

Official documentation: employee_updates/new_hires

Parameters:: kwargs (optional) – Optional keyword arguments (e.g. params for query string) forwarded to the HTTP request.
Raises:: httpx.HTTPStatusError – When the API returns an error status code.
Returns:: Response containing the list of records.
Return type:: ListApiResponse[EmployeeNewHire]

async get(**kwargs) → MetaApiResponse[EmployeeNewHire][source]

Get new hires with pagination metadata.

Official documentation: employee_updates/new_hires

Parameters:: kwargs (optional) – Optional keyword arguments (e.g. params for query string) forwarded to the HTTP request.
Raises:: httpx.HTTPStatusError – When the API returns an error status code.
Returns:: Response containing records and pagination metadata.
Return type:: MetaApiResponse[EmployeeNewHire]

async get_by_id(new_hire_id: int | str, **kwargs) → EmployeeNewHire[source]

Get a specific new hire by ID.

Official documentation: employee_updates/new_hires

Parameters:

new_hire_id (int | str) – The unique identifier.
kwargs (optional) – Optional keyword arguments (e.g. params for query string) forwarded to the HTTP request.

Raises:

httpx.HTTPStatusError – When the API returns an error status code.

Returns:

The record.

Return type:

EmployeeNewHire

class factorialhr.PersonalChangesEndpoint(api: ApiClient)[source]

Endpoint for employee_updates/personal_changes operations.

async all(**kwargs) → ListApiResponse[EmployeePersonalChange][source]

Get all personal changes records.

Official documentation: employee_updates/personal_changes

Parameters:: kwargs (optional) – Optional keyword arguments (e.g. params for query string) forwarded to the HTTP request.
Raises:: httpx.HTTPStatusError – When the API returns an error status code.
Returns:: Response containing the list of records.
Return type:: ListApiResponse[EmployeePersonalChange]

async get(**kwargs) → MetaApiResponse[EmployeePersonalChange][source]

Get personal changes with pagination metadata.

Official documentation: employee_updates/personal_changes

Parameters:: kwargs (optional) – Optional keyword arguments (e.g. params for query string) forwarded to the HTTP request.
Raises:: httpx.HTTPStatusError – When the API returns an error status code.
Returns:: Response containing records and pagination metadata.
Return type:: MetaApiResponse[EmployeePersonalChange]

async get_by_id(personal_change_id: int | str, **kwargs) → EmployeePersonalChange[source]

Get a specific personal change by ID.

Official documentation: employee_updates/personal_changes

Parameters:

personal_change_id (int | str) – The unique identifier.
kwargs (optional) – Optional keyword arguments (e.g. params for query string) forwarded to the HTTP request.

Raises:

httpx.HTTPStatusError – When the API returns an error status code.

Returns:

The record.

Return type:

EmployeePersonalChange

class factorialhr.SummariesEndpoint(api: ApiClient)[source]

Endpoint for employee_updates/summaries operations.

async all(**kwargs) → ListApiResponse[EmployeeSummary][source]

Get all summaries records.

Official documentation: employee_updates/summaries

Parameters:: kwargs (optional) – Optional keyword arguments (e.g. params for query string) forwarded to the HTTP request.
Raises:: httpx.HTTPStatusError – When the API returns an error status code.
Returns:: Response containing the list of records.
Return type:: ListApiResponse[EmployeeSummary]

async get(**kwargs) → MetaApiResponse[EmployeeSummary][source]

Get summaries with pagination metadata.

Official documentation: employee_updates/summaries

Parameters:: kwargs (optional) – Optional keyword arguments (e.g. params for query string) forwarded to the HTTP request.
Raises:: httpx.HTTPStatusError – When the API returns an error status code.
Returns:: Response containing records and pagination metadata.
Return type:: MetaApiResponse[EmployeeSummary]

async get_by_id(summary_id: int | str, **kwargs) → EmployeeSummary[source]

Get a specific summary by ID.

Official documentation: employee_updates/summaries

Parameters:

summary_id (int | str) – The unique identifier.
kwargs (optional) – Optional keyword arguments (e.g. params for query string) forwarded to the HTTP request.

Raises:

httpx.HTTPStatusError – When the API returns an error status code.

Returns:

The record.

Return type:

EmployeeSummary

class factorialhr.TerminationsEndpoint(api: ApiClient)[source]

Endpoint for employee_updates/terminations operations.

async all(**kwargs) → ListApiResponse[EmployeeTermination][source]

Get all terminations records.

Official documentation: employee_updates/terminations

Parameters:: kwargs (optional) – Optional keyword arguments (e.g. params for query string) forwarded to the HTTP request.
Raises:: httpx.HTTPStatusError – When the API returns an error status code.
Returns:: Response containing the list of records.
Return type:: ListApiResponse[EmployeeTermination]

async get(**kwargs) → MetaApiResponse[EmployeeTermination][source]

Get terminations with pagination metadata.

Official documentation: employee_updates/terminations

Parameters:: kwargs (optional) – Optional keyword arguments (e.g. params for query string) forwarded to the HTTP request.
Raises:: httpx.HTTPStatusError – When the API returns an error status code.
Returns:: Response containing records and pagination metadata.
Return type:: MetaApiResponse[EmployeeTermination]

async get_by_id(termination_id: int | str, **kwargs) → EmployeeTermination[source]

Get a specific termination by ID.

Official documentation: employee_updates/terminations

Parameters:

termination_id (int | str) – The unique identifier.
kwargs (optional) – Optional keyword arguments (e.g. params for query string) forwarded to the HTTP request.

Raises:

httpx.HTTPStatusError – When the API returns an error status code.

Returns:

The record.

Return type:

EmployeeTermination