Employees

The /api/v1/employees endpoint group covers the full employee synchronization cycle with external HR and payroll systems: creating employee records, updating personal data, maintaining historical tables for employments, positions, and compensations, and archiving terminated employees.

Core employee operations

Create an employee

POST /api/v1/employees

Creates a new employee record. Email is not required at creation time.

Required fields:

Field	Type	Description
`first_name`	string	First name
`last_name`	string	Last name
`date_effective_from`	string (date)	Hire date

Optional fields:

Field	Description
`middle_name`	Middle name
`division_id`	Division ID
`department_id`	Department ID
`position_id`	Position ID
`position_level_id`	Grade / level ID
`location_id`	Location ID
`legal_entity_id`	Legal entity ID
`reporting_to_id`	Manager ID
`employment_contract_id`	Employment contract type ID
`employment_type_id`	Employment type ID
`employment_work_pattern_id`	Work pattern ID
`base_salary_gross`	Gross salary
`base_salary_net`	Net salary
`currency`	Currency code (ISO 4217)
`per_type`	Period: `hourly`, `weekly`, `monthly`, `yearly`

Request example:

{
  "first_name": "John",
  "last_name": "Smith",
  "date_effective_from": "2024-01-15",
  "department_id": 42,
  "position_id": 7,
  "base_salary_gross": "150000",
  "currency": "USD",
  "per_type": "monthly"
}

Get employee details

GET /api/v1/employees/{employee_id}

Returns the full employee profile including current position, employment, compensation, and custom fields (custom_fields).

Update personal data

PUT /api/v1/employees/{employee_id}

Updates personal data and custom fields in a single request.

Required fields: first_name, last_name

Optional fields:

Field	Description
`email`	Work email
`email_personal`	Personal email
`phone`	Work phone
`phone_personal`	Personal phone
`date_birth`	Date of birth
`gender`	Gender
`personnel_number`	Personnel number
`address_1`, `address_2`, `city`, `state`, `zip`	Address fields
`country_id`	Country ID
`custom_fields`	dict `{slug: value}` - employee custom field values

Request example:

{
  "first_name": "John",
  "last_name": "Smith",
  "email": "[email protected]",
  "personnel_number": "EMP-001",
  "custom_fields": {
    "tax_id": "123456789"
  }
}

Archive an employee

DELETE /api/v1/employees/{employee_id}

Soft-deletes the employee (termination). All data is preserved.

Position history

A position record captures department, job title, manager, and location at a specific effective date.

Add a position record

POST /api/v1/employees/{employee_id}/positions

Field	Type	Description
`date_effective_from`	string (date)	Effective start date
`division_id`	integer	Division ID
`department_id`	integer	Department ID
`position_id`	integer	Position ID
`position_level_id`	integer	Grade/level ID
`reporting_to_id`	integer	Manager ID
`legal_entity_id`	integer	Legal entity ID
`location_id`	integer	Location ID
`comment`	string	Comment

Update / delete a position record

PUT    /api/v1/employees/{employee_id}/positions/{id}
DELETE /api/v1/employees/{employee_id}/positions/{id}

Search position history

POST /api/v1/employees/{employee_id}/positions/search

Returns a paginated list of position records with full nested objects: department, division, position, manager, legal_entity, location.

Employment history

An employment record captures contract type, employment type, work pattern, and the employment period.

Get employment history

GET /api/v1/employees/{employee_id}/employments

Returns the full list of employment records (current and past).

Add an employment record

POST /api/v1/employees/{employee_id}/employments

Field	Type	Description
`date_effective_from`	string (date)	Start date (hire date)
`date_effective_to`	string (date)	End date / termination date
`employment_type_id`	integer	Employment type ID
`employment_contract_id`	integer	Contract type ID
`work_pattern_id`	integer	Work pattern ID
`date_probation_ends`	string (date)	Probation end date
`comment`	string	Comment

Update / delete an employment record

PUT    /api/v1/employees/{employee_id}/employments/{id}
DELETE /api/v1/employees/{employee_id}/employments/{id}

Compensation history

A compensation record captures base salary (gross/net) effective from a specific date.

Add a compensation record

POST /api/v1/employees/{employee_id}/compensations

Field	Type	Description
`date_effective_from`	string (date)	Effective start date
`base_salary_gross`	number	Gross salary
`base_salary_net`	number	Net salary
`currency`	string	Currency (ISO 4217)
`per_type`	string	`hourly`, `weekly`, `monthly`, `yearly`
`change_reason_id`	integer	Change reason ID
`comment`	string	Comment

Search compensation history

POST /api/v1/employees/{employee_id}/compensations/search

Returns a paginated list of compensation records.

Update / delete a compensation record

PUT    /api/v1/employees/{employee_id}/compensations/{id}
DELETE /api/v1/employees/{employee_id}/compensations/{id}

Additional compensations

Additional compensations are bonuses and allowances stored as a separate entity (not to be confused with custom table rows).

Get all additional compensations

GET /api/v1/employees/{employee_id}/additional-compensations

Create an additional compensation

POST /api/v1/employees/{employee_id}/additional-compensations

Field	Type	Description
`compensation_type_id`	integer	Compensation type ID (required)
`type`	string	`one_time` or `recurring` (required)
`amount`	number	Amount (required)
`date_effective_from`	string (date)	Effective start date (required)
`date_effective_to`	string (date)	Effective end date
`frequency_type`	string	`monthly`, `quarterly`, `yearly` (for recurring)
`currency`	string	Currency code
`description`	string	Description
`comment`	string	Comment

Update / delete an additional compensation

PUT    /api/v1/employees/{employee_id}/additional-compensations/{id}
DELETE /api/v1/employees/{employee_id}/additional-compensations/{id}

Custom table rows

Write rows to custom tables linked to an employee (e.g. “Accrued Bonuses”, “Payment Details”). Get the list of available tables and their field slugs via GET /api/v1/custom-fields/tables.

Add a row

POST /api/v1/employees/{employee_id}/field-tables/{table_id}/rows

Field	Type	Description
`date_effective_from`	string (date)	Effective date of this row
`cells`	object	`{slug: value}` - cell values

Supported value types in cells:

text / textarea / email / phone - string
number / currency / percentage - number
date - string YYYY-MM-DD
datetime - ISO 8601 string
select - option ID
switch - boolean
employee_reference - integer (employee ID)

Request example:

{
  "date_effective_from": "2024-01-01",
  "cells": {
    "bonus_amount": 5000,
    "bonus_currency": 1,
    "bonus_comment": "Q1 performance bonus"
  }
}

Update / delete a row

PUT    /api/v1/employees/{employee_id}/field-tables/{table_id}/rows/{id}
DELETE /api/v1/employees/{employee_id}/field-tables/{table_id}/rows/{id}

Typical integration scenario

Full new-hire sync from an HR/payroll system:

Create the employee - POST /api/v1/employees with basic data and hire date.
Update personal data - PUT /api/v1/employees/{id} with email, phone, and custom fields.
Record employment - POST /api/v1/employees/{id}/employments with contract type.
Record compensation - POST /api/v1/employees/{id}/compensations with salary.
Write custom table rows - POST /api/v1/employees/{id}/field-tables/{table_id}/rows for bonuses, payment details, etc.

On termination:

Close the employment record - PUT /api/v1/employees/{id}/employments/{id} (add date_effective_to).
Archive the employee - DELETE /api/v1/employees/{id}.