Employees Service

The `EmployeesService` is your primary tool for creating and retrieving Employee records, as well as managing their associated payroll classes and settings.

Importing Helpers

To create employees and their related settings, you will need to import the relevant builders from the `easy_acumatica.models` module.


from easy_acumatica.models.employee_builder import EmployeeBuilder
from easy_acumatica.models.employee_payroll_class_builder import EmployeePayrollClassBuilder
from easy_acumatica.models.employee_payroll_settings_builder import EmployeePayrollSettingsBuilder
from easy_acumatica.models.query_builder import QueryOptions

Service Methods

get_employees(api_version, options=None)

This is the main method for fetching a list of employee records. It can be used to get all employees or a filtered, specific list by using `QueryOptions`.


# Create a filter to find a specific employee
employee_filter = F.EmployeeID == 'EP00000001'

# Use QueryOptions to expand all related settings objects
opts = QueryOptions(
    filter=employee_filter,
    expand=["ContactInfo", "EmployeeSettings", "FinancialSettings"]
)

# Fetch the employee data
employees = client.employees.get_employees("24.200.001", options=opts)

create_employee(api_version, builder, options=None)

Use this method to create a new employee record. You must provide an `EmployeeBuilder` object containing the new employee's details. The builder helps construct the required nested JSON structure for contact info, employee settings, and financial settings.


# Build the employee payload using the fluent builder
employee_payload = (
    EmployeeBuilder()
    .status("Active")
    .contact_info(first_name="Jane", last_name="Doe")
    .employee_settings(branch_id="HEADOFFICE", department_id="SALES")
    .financial_settings(payment_method="CHECK")
)

# Create the employee
new_employee = client.employees.create_employee(
    "24.200.001", 
    builder=employee_payload
)

create_employee_payroll_class(api_version, builder)

Creates a new employee payroll class, which acts as a template for payroll settings that can be applied to multiple employees.


# Build the payload for a new payroll class
payroll_class_payload = (
    EmployeePayrollClassBuilder()
    .employee_payroll_class_id("SALARIED")
    .description("Salaried Employees, Bi-Weekly")
    .payroll_defaults(EmployeeType="Salaried", PayGroup="BIWEEKLY")
)

# Create the payroll class
new_class = client.employees.create_employee_payroll_class(
    "24.200.001",
    builder=payroll_class_payload
)

update_employee_payroll_settings(api_version, builder, ...)

Updates the payroll settings for a specific employee. This is used to assign a payroll class, set payment methods, define work locations, and more.


# Build the payload to update a specific employee's payroll settings
payroll_settings_payload = (
    EmployeePayrollSettingsBuilder()
    .employee_id("EP00000004")
    .class_id("SALARIED")
    .payment_method("DIRECT")
    .cash_account("10200")
)

# Update the employee's payroll settings
updated_settings = client.employees.update_employee_payroll_settings(
    "24.200.001",
    builder=payroll_settings_payload
)