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

# Holidays

> Query country holidays and manage company days off and exclusions

| Operation | Permission |
| - | - |
| Query holidays | `hr.holidays` |
| Create, edit and delete company days off; exclude country holidays | `hr.holidays.write` |

See [Holidays and days off](https://docs.filexpress.app/en/docs/rrhh/feriados.md) in the manual.

## List holidays

```http theme={null}
GET /hr/holidays?year=2026
```

**Required permission:** `hr.holidays`

| Parameter | Required | Description |
| - | - | - |
| `year` | No | Year (2000–2100). Defaults to the current one. |

Returns the holidays of the company's country and the company's own days off, sorted by date.

```json theme={null}
{
  "status": true,
  "data": [
    {
      "id": "uuid",
      "business_id": null,
      "country_code": "SV",
      "date": "2026-11-02",
      "name": "Día de los Difuntos",
      "scope": "national",
      "region_code": null,
      "branch_id": null,
      "action": "add",
      "start_time": null,
      "is_paid": true,
      "source": "generator",
      "origin": "country",
      "is_excluded": true,
      "exclusion_id": "uuid"
    },
    {
      "id": "uuid",
      "business_id": "uuid",
      "country_code": "SV",
      "date": "2026-12-24",
      "name": "Nochebuena",
      "scope": "company",
      "region_code": null,
      "branch_id": null,
      "action": "add",
      "start_time": "12:00",
      "is_paid": true,
      "source": "manual",
      "origin": "company",
      "is_excluded": false,
      "exclusion_id": null
    }
  ]
}
```

| Field | Description |
| - | - |
| `origin` | `country` (country holiday) or `company` (company day off). |
| `scope` | `national`, `regional` (local day off for reference, **not applied automatically**) or `company`. |
| `start_time` | If it has a value, it is a half-day holiday from that time. |
| `branch_id` | Day off limited to one branch. `null` = the whole company. |
| `is_excluded`, `exclusion_id` | The company excluded this country holiday. To remove the exclusion, delete `exclusion_id` with `DELETE /hr/holidays/{exclusion_id}`. |

## Create a day off

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

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

Creates **one** company day off per call.

```json theme={null}
{
  "date": "2026-12-24",
  "name": "Nochebuena",
  "branch_id": null,
  "start_time": "12:00",
  "is_paid": true
}
```

| Field | Required | Description |
| - | - | - |
| `date` | Yes | Date (`YYYY-MM-DD`). |
| `name` | Yes | Name (max. 255). It cannot be repeated on the same date. |
| `branch_id` | No | Company branch (`GET /branches`). |
| `start_time` | No | `HH:MM`: day off from that time (half day). |
| `is_paid` | No | Paid. Defaults to `true`. |

**`201` response**: the day off (same format as the list) with `recalculation_queued`.

| Code | Cause |
| - | - |
| `422` | Validation, branch from another company or name repeated on the date. |

## Edit a day off

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

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

Send only the fields that change. Only company days off can be edited; a country holiday or an exclusion returns `404`.

**`200` response**: the updated day off with `recalculation_queued`.

## Delete a day off or exclusion

```http theme={null}
DELETE /hr/holidays/{id}
```

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

Deletes a company day off or an exclusion (`exclusion_id`). Country holidays are not deleted: they are excluded.

```json theme={null}
{ "status": true, "data": { "id": "uuid", "deleted": true, "recalculation_queued": true } }
```

## Exclude a country holiday

```http theme={null}
POST /hr/holidays/{id}/exclude
```

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

`{id}` is a holiday of the company's country (`origin: country`). That day is treated as a normal day for the company.

**Behavior**

* **Idempotent**: excluding the same holiday twice does not create another exclusion.

**`200` response**: the country holiday with `is_excluded: true`, its `exclusion_id` and `recalculation_queued`.

> [!NOTE]
>
> Any change to holidays recalculates attendance for that date. Days included in processed or paid payrolls do not change.


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