Custom Tables

Custom tables are user-defined data tables configured in the Skailer interface. Examples: “Accrued Bonuses”, “Paid Bonuses”, “Payment Details”, etc. The API lets you read the table configuration and retrieve rows with filtering.

Get all custom tables

GET /api/v1/custom-fields/tables

Returns all custom tables of the organization configured for employees.

Response fields (per table):

Field	Type	Description
id	integer	Table ID
slug	string	Unique table slug
title	string	Table name
table_type	string	Table type (see below)
is_historical	boolean	Whether the table is historical (date-effective rows)
table_fields	array	List of table fields

Table types (table_type):

Value	Description
custom	User-defined custom table
employee_positions	System position history table
employee_employments	System employment history table
employee_compensations	System compensation history table
employee_additional_compensations	System additional compensations table

Fields per table field (table_fields):

Field	Type	Description
id	integer	Field ID
slug	string	Field slug (used as key in cells when writing rows)
title	string	Field name
field_type	string	Value type: text, number, date, datetime, select, switch, employee_reference, etc.
options	array	Options for select fields
is_mandatory	boolean	Whether the field is mandatory
is_archived	boolean	Whether the field is archived

Response example:

[
  {
    "id": 15,
    "slug": "accrued_bonuses",
    "title": "Accrued Bonuses",
    "table_type": "custom",
    "is_historical": true,
    "table_fields": [
      {
        "id": 101,
        "slug": "bonus_amount",
        "title": "Amount",
        "field_type": "number",
        "options": []
      },
      {
        "id": 102,
        "slug": "bonus_currency",
        "title": "Currency",
        "field_type": "select",
        "options": [
          { "id": 1, "title": "USD" },
          { "id": 2, "title": "EUR" }
        ]
      }
    ]
  }
]

---

Search rows in a custom table

POST /api/v1/custom-fields/tables/{table_id}/rows/search

Search and export rows from a specific table. Supports filtering, pagination, and sorting.

Request parameters:

Field	Type	Description
page_number	integer	Page number (default: 1)
employee_ids	array[integer]	Filter by employees
position_ids	array[integer]	Filter by positions
department_ids	array[integer]	Filter by departments
division_ids	array[integer]	Filter by divisions
location_ids	array[integer]	Filter by locations
employee_lifecycle_statuses	array[string]	Statuses: hired, employed, terminated, on_leave, on_parental_leave
date_effective_from	string (date)	Rows effective on or after this date
date_effective_to	string (date)	Rows effective on or before this date
field_filters	array	Custom filters on field values
sorting	object	Sort configuration
text	string	Text search

Response fields (per row):

Field	Type	Description
id	integer	Row ID
employee_id	integer	Employee ID
date_effective_from	string	Row effective date
is_current	boolean	Whether this is the current row
cells	array	Filled cells with values and field configuration

Request example - export bonuses for a quarter:

{
  "page_number": 1,
  "date_effective_from": "2024-01-01",
  "date_effective_to": "2024-03-31",
  "employee_lifecycle_statuses": ["employed"]
}

---

Typical integration scenario

Goal: export employee bonuses for a period to a payroll system.

1. Get table list:

   GET /api/v1/custom-fields/tables

   Find the table with the target slug, save its id and field ids.

2. Fetch rows for the period:

   POST /api/v1/custom-fields/tables/{table_id}/rows/search

   Use date_effective_from / date_effective_to filters.

3. Use the field slug from the table configuration to interpret cell values.

Tip: cache the table configuration (step 1) - it changes infrequently. Fetch rows (step 2) on every sync run.

---

Writing rows to tables

To add, update, or delete rows for a specific employee, use the methods described in Employees → Custom table rows.