Employees

Usage

Fetch employees and use their data:

import asyncio
import factorialhr

async def main():
    auth = factorialhr.AccessTokenAuth("your_access_token")
    async with factorialhr.ApiClient(auth=auth) as api:
        employees = factorialhr.EmployeesEndpoint(api)
        response = await employees.all()
        for employee in response.data():
            print(employee.first_name, employee.last_name, employee.email)
        # Or get a single employee by ID
        one = await employees.get_by_id(123)
        print(one.first_name)

asyncio.run(main())

class factorialhr.Employee(*, id: int, access_id: int, first_name: str, last_name: str, full_name: str, preferred_name: str | None = None, birth_name: str | None = None, gender: str | None = None, identifier: str | None = None, identifier_type: str | None = None, email: str | None = None, login_email: str | None = None, birthday_on: date | None = None, nationality: str | None = None, address_line_1: str | None = None, address_line_2: str | None = None, postal_code: str | None = None, city: str | None = None, state: str | None = None, country: str | None = None, bank_number: str | None = None, swift_bic: str | None = None, bank_number_format: BankNumberFormat | None = None, company_id: int, legal_entity_id: int | None = None, location_id: int, created_at: datetime, updated_at: datetime, social_security_number: str | None = None, is_terminating: bool, terminated_on: date | None = None, termination_reason_type: str | None = None, termination_reason: str | None = None, termination_observations: str | None = None, manager_id: int | None = None, timeoff_manager_id: int | None = None, phone_number: str | None = None, company_identifier: str | None = None, age_number: int | None = None, termination_type_description: str | None = None, contact_name: str | None = None, contact_number: str | None = None, personal_email: str | None = None, seniority_calculation_date: date | None = None, pronouns: str | None = None, active: bool | None = None, disability_percentage_cents: int | None = None, identifier_expiration_date: date | None = None, attendable: bool, country_of_birth: str | None = None, birthplace: str | None = None)

Model for employees_employee.

access_id: int

Access_id associated to the employee

active: bool | None

Status of the employee, true when active, false when terminated

address_line_1: str | None

Address of the employee

address_line_2: str | None

Secondary address of the employee

age_number: int | None

Age of the employee

attendable: bool

Employee included in a time tracking policy

bank_number: str | None

Bank account number of the employee

bank_number_format: BankNumberFormat | None

Bank number format

birth_name: str | None

Birthname of the employee

birthday_on: date | None

Birthday of the employee

birthplace: str | None

Birthplace of the employee

city: str | None

City of the employee

company_id: int

Id of the company to which the employee belongs (not editable)

company_identifier: str | None

Identity number or string used inside a company to internally identify the employee

contact_name: str | None

Name of the employee contact

contact_number: str | None

Phone number of the employee contact

country: str | None

Country code of the employee (Spain ES, United Kingdom GB)

country_of_birth: str | None

Country of birth of the employee

created_at: datetime

Creation date of the employee

disability_percentage_cents: int | None

Officially certified level of disability granted by public administration for individuals with physical or mental impairments, expressed in cents

email: str | None

Personal email of the employee

first_name: str

Name of the employee

full_name: str

Full name of the employee

gender: str | None

Gender of the employee (male | female)

id: int

Id of the employee

identifier: str | None

National identifier number

identifier_expiration_date: date | None

Identifier expiration date

identifier_type: str | None

Type of identifier (ex passport)

is_terminating: bool

Is the employee being terminated?

last_name: str

Last name of the employee

legal_entity_id: int | None

Legal entity of the employee, references to companies/legal_entities

location_id: int

Location id of the employee, references to locations/locations

login_email: str | None

Email associated to the session

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)

personal_email: str | None

Personal email of the employee

phone_number: str | None

Phone number of the employee

postal_code: str | None

Postal code of the employee

preferred_name: str | None

Nickname of the employee or a name that defines the employee better

pronouns: str | None

Pronouns that an employee uses to define themselves

seniority_calculation_date: date | None

Date since when the employee is working in the company

social_security_number: str | None

Social security number of the employee

state: str | None

State/province/region of the employee

swift_bic: str | None

Code to identify banks and financial institutions globally

terminated_on: date | None

Termination date of the employee

termination_observations: str | None

Observations about the termination

termination_reason: str | None

A reason for the termination

termination_reason_type: str | None

Termination reason type of the employee

termination_type_description: str | None

The description of the termination type

timeoff_manager_id: int | None

Timeoff manager id of the employee

updated_at: datetime

Date of last modification of the employee

class factorialhr.EmployeesEndpoint(api: ApiClient)

Endpoint for employees/employees operations.

async all(**kwargs) → ListApiResponse[Employee]

Get all employees records.

Official documentation: employees/employees

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[Employee]

async create_with_contract(data: Mapping[str, Any], **kwargs) → Employee

Create an employee with contract.

Official documentation: employees/employees

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:

Employee

async get(**kwargs) → MetaApiResponse[Employee]

Get employees with pagination metadata.

Official documentation: employees/employees

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[Employee]

async get_by_id(employee_id: int | str, **kwargs) → Employee

Get a specific employee by ID.

Official documentation: employees/employees

Parameters:

• employee_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:

Employee

async invite(data: Mapping[str, Any], **kwargs) → Employee

Invite an employee.

Official documentation: employees/employees

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:

Result.

Return type:

Employee

async set_regular_access_start_date(data: Mapping[str, Any], **kwargs) → Employee

Set regular access start date for an employee.

Official documentation: employees/employees

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:

Result.

Return type:

Employee

async terminate(data: Mapping[str, Any], **kwargs) → Employee

Terminate an employee.

Official documentation: employees/employees

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:

Result.

Return type:

Employee

async unterminate(data: Mapping[str, Any], **kwargs) → Employee

Unterminate an employee.

Official documentation: employees/employees

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:

Result.

Return type:

Employee

async update(employee_id: int | str, data: Mapping[str, Any], **kwargs) → Employee

Update an employee.

Official documentation: employees/employees

Parameters:

• employee_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:

Employee