> ## 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.

# Leave and vacation

> Create and query leave requests

**Required permission:** `hr.leave_requests`

## Create request

```http theme={null}
POST /hr/leave-requests
```

The request is created in **`pending`** status. Approval or rejection (and the deduction from the vacation balance) is always done by Human Resources inside FileXpress.

```json theme={null}
{
  "document_number": "01234567-8",
  "type": "vacation",
  "start_date": "2026-12-22",
  "end_date": "2026-12-31",
  "reason": "Vacaciones anuales"
}
```

| Field | Required | Description |
| - | - | - |
| `employee_id` or `document_number` | Yes (one) | Employee. |
| `type` | Yes | `vacation` (vacation), `sick_leave` (medical leave), `personal_leave` (personal leave), `unpaid_leave` (unpaid leave) or `other`. |
| `start_date` | Yes | First day (`YYYY-MM-DD`). |
| `end_date` | Yes | Last day (equal to or later than `start_date`). |
| `reason` | No | Reason (max. 1000 characters). |

> [!NOTE]
>
> Approved `unpaid_leave` requests are automatically deducted in the period's payroll.

**Days to deduct**

When the request is created, FileXpress calculates the days to deduct according to the counting method in the country's [labor rules](https://docs.filexpress.app/en/docs/api/rrhh/reglas-laborales.md) (`leave.vacation_day_counting` and `leave.other_day_counting`): in **calendar days** (the default in El Salvador and for non-vacation leave) or in **business days** (the default for vacation in Guatemala and Colombia), not counting the employee's schedule rest days or holidays. This is what is deducted from the balance when vacation is approved in FileXpress. See [how days are counted](https://docs.filexpress.app/en/docs/rrhh/permisos.md#how-days-are-counted).

> [!NOTE]
>
> Through the external API the request does not validate the vacation balance (it is validated on approval). It supports `half_day: true` only when `start_date` and `end_date` are the same day (otherwise it responds `422`). When created, FileXpress sends the *New leave request* notification (bell and app push) to the company administrators and to the employee's direct manager, just like requests created in FileXpress.

**Response `201`**: the request object (see below).

**Errors**

| Code | Cause |
| - | - |
| `404` | Employee not found. |
| `422` | Validation error, inactive employee, or `half_day` on a range of more than one day. |
| `409` | The employee already has a pending or approved request that overlaps with those dates. |

## Query requests

```http theme={null}
GET /hr/leave-requests?start_date=2026-10-01&end_date=2026-12-31&status=approved
```

Returns the requests that overlap with the range.

| Parameter | Required | Description |
| - | - | - |
| `start_date`, `end_date` | Yes | Range (maximum 93 days). |
| `employee_id` | No | Filters by employee. |
| `status` | No | `pending`, `approved`, `rejected` or `cancelled`. |
| `type` | No | Leave type. |

```json theme={null}
{
  "status": true,
  "data": [
    {
      "id": "uuid",
      "employee_id": "uuid",
      "employee_name": "María López",
      "document_number": "01234567-8",
      "type": "vacation",
      "start_date": "2026-12-22",
      "end_date": "2026-12-31",
      "days": 10,
      "status": "approved",
      "reason": "Vacaciones anuales"
    }
  ]
}
```

| Field | Description |
| - | - |
| `days` | **Calendar** days in the range (`end_date - start_date + 1`). It does not reflect the business-day count: the days deducted from the balance can be seen in FileXpress. |
| `status` | `pending`, `approved`, `rejected` or `cancelled`. |


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