> ## Documentation Index
> Fetch the complete documentation index at: https://docs.filexpress.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Employees

> Query, create and update employees

| Operation | Permission |
| - | - |
| Query employees and job titles | `hr.employees` |
| Create and update employees | `hr.employees.write` |

> [!WARNING]
>
> This permission exposes personal data and salaries. Protect the API Key and limit access to trusted systems.

## List employees

```http theme={null}
GET /hr/employees
```

| Parameter | Type | Description |
| - | - | - |
| `is_active` | boolean | Filters active (`1`) or inactive (`0`). Without the parameter it returns both. |
| `search` | string | Searches by first name, last name or email. |
| `document_number` | string | Filters by exact document number. |
| `per_page` | integer | Results per page (1–200, default 50). |
| `page` | integer | Page. |

```json theme={null}
{
  "status": true,
  "data": {
    "data": [
      {
        "id": "uuid",
        "first_name": "María",
        "last_name": "López",
        "document_type": "DUI",
        "document_number": "01234567-8",
        "tax_number": "0614-010190-101-1",
        "email": "maria@empresa.com",
        "phone": "7000-0000",
        "type": "permanent",
        "job_title": "Contadora",
        "hire_date": "2024-02-01",
        "salary": 850.00,
        "employment_relationship": "labor",
        "pay_type": "salaried",
        "hourly_rate": null,
        "is_active": true
      }
    ],
    "pagination": { "current_page": 1, "last_page": 1, "per_page": 50, "total": 1 }
  }
}
```

| Field | Description |
| - | - |
| `type` | Contract type: `permanent`, `temporary` or `project_based`. |
| `salary` | Monthly salary. |
| `hire_date` | Hire date. |
| `employment_relationship` | Relationship: `labor` (employment) or `services` (professional services). |
| `pay_type` | Pay type: `salaried` (monthly salary), `hourly` (per hour) or `fee` (fees). |
| `hourly_rate` | Hourly rate, or `null`. |

## Get employee

```http theme={null}
GET /hr/employees/{id}
```

Returns the same employee object. Deleted employees respond `404`.

## Job titles

```http theme={null}
GET /hr/job-titles
```

Returns the job title catalog (`id`, `name`, `description`, `parent_id`) so you can get the `job_title_id`. Requires `hr.employees`.

## Create employee

```http theme={null}
POST /hr/employees
```

**Required permission:** `hr.employees.write`

```json theme={null}
{
  "first_name": "María",
  "last_name": "López",
  "document_type": "DUI",
  "document_number": "01234567-8",
  "tax_number": "0614-010190-101-1",
  "email": "maria@empresa.com",
  "phone": "7000-0000",
  "type": "permanent",
  "job_title_id": "uuid",
  "manager_id": "uuid",
  "hire_date": "2026-10-01",
  "salary": 850.00,
  "bank_name": "Banco Agrícola",
  "bank_account_type": "Ahorro",
  "bank_account_number": "3000123456"
}
```

| Field | Required | Description |
| - | - | - |
| `first_name`, `last_name` | Yes | First and last names. |
| `type` | Yes | `permanent`, `temporary` or `project_based`. |
| `hire_date` | Yes | Hire date (`YYYY-MM-DD`). Used for seniority, Christmas bonus (aguinaldo), vacation and final settlement (finiquito). |
| `salary` | Yes | Monthly salary. |
| `document_type`, `document_number` | No | Identity document. The number must be **unique** in the business: it is used to identify clock-ins and leave requests. |
| `tax_number` | No | NIT. |
| `email`, `phone`, `address` | No | Contact. |
| `birth_date` | No | Date of birth. |
| `job_title_id` | No | Job title (`GET /hr/job-titles`). |
| `manager_id` | No | Direct manager (ID of another employee). |
| `emergency_contact_name`, `emergency_contact_phone` | No | Emergency contact. |
| `bank_name`, `bank_account_type`, `bank_account_number` | No | Account for payroll payment. |
| `employment_relationship` | No | `labor` (default) or `services`. With `services`, legal surcharges are not applied to hours. |
| `pay_type` | No | `salaried` (default), `hourly` or `fee`. Defines how hours are valued in the [attendance results](https://docs.filexpress.app/en/docs/api/rrhh/resultados-asistencia.md). |
| `hourly_rate` | Conditional | Hourly rate (≥ 0). **Required** if `pay_type` is `hourly`. |
| `is_active` | No | Defaults to `true`. |

**`201` response**: the created employee (same format as the query).

| Code | Cause |
| - | - |
| `409` | An employee with that document number already exists. The response includes their `employee_id`. |
| `422` | Validation: required fields, job title or manager not found in the business, or `pay_type: hourly` without `hourly_rate`. |

## Update employee

```http theme={null}
PUT /hr/employees/{id}
```

**Required permission:** `hr.employees.write`

Send only the fields that change; the others are kept. Accepts the same fields as creation.

```json theme={null}
{ "salary": 950.00, "job_title_id": "uuid" }
```

To switch an employee to hourly pay:

```json theme={null}
{ "pay_type": "hourly", "hourly_rate": 3.25 }
```

To deactivate an employee, send `{ "is_active": false }`. The API does not delete employees: this keeps their payroll history. Their settlement is calculated with the [final settlement (finiquito)](https://docs.filexpress.app/en/docs/rrhh/finiquitos.md) in FileXpress.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.