Absences

The absence domain has two layers: a configuration layer (what can be requested and how much) and a workflow layer (requests, balances and the calendar). Everything is scoped by absences:read / absences:write and gated by the control_horario module, under https://api.factuarea.com/v1.

Absence types

An absence type is what an employee can request — holiday, sick leave, a personal day. Each type carries: whether it is paid (is_paid), whether it requires approval (requires_approval), a measurement unit (days or hours), a hex color, a visibility (everyone or managers_only) and a status (active / archived). The name is unique per company. A default set of Spanish types is seeded into every new company, so you usually start with a working catalogue.

curl -X POST https://api.factuarea.com/v1/absence-types \
  -H "Authorization: Bearer $FACTUAREA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Personal leave",
    "is_paid": true,
    "requires_approval": true,
    "measurement_unit": "days",
    "color": "#4F46E5",
    "visibility": "everyone"
  }'

Absence policies

An absence policy decides how much and for whom. It sets an allowance — limited (a positive number of days) or unlimited — an accrual method (annual or monthly), the set of types it covers, and the employees it is assigned to. Assigning types is a full replacement; a policy is assigned to and unassigned from employees in batches.

Carryover exposes how much unused allowance rolls over into the next accrual period per employee. Assignment always resolves the employee inside the authenticated company, so a policy of company A is never assigned to an employee of company B.

curl -X POST https://api.factuarea.com/v1/absence-policies \
  -H "Authorization: Bearer $FACTUAREA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Standard 22 days",
    "allowance": { "type": "limited", "days": 22 },
    "accrual_method": "annual",
    "absence_type_ids": ["01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0b"]
  }'

Requests, balances and calendar

Once types and policies exist, employees request absences and managers resolve them.

A balance is the remaining allowance per employee and type, derived from the policy accrual minus approved requests. The calendar returns the team's absences over a date range — the manager view of who is off and when.

curl -X POST https://api.factuarea.com/v1/absence-requests \
  -H "Authorization: Bearer $FACTUAREA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "employee_id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0b",
    "absence_type_id": "01931b3e-7c4a-7f2e-9a8b-4d6e7f8a9b0c",
    "start_date": "2026-08-01",
    "end_date": "2026-08-15"
  }'

Typical flow

1. Review the seeded types, or create your own.
2. Create policies with an allowance and accrual, and cover the relevant types.
3. Assign each policy to its employees.
4. Employees request; managers approve or reject.
5. Read balances and the calendar, and check carryover at year end.

Public holidays that affect absences live in their own read-only domain — see the overview and the holidays reference.

Next steps

• Monthly close — approved absences feed the monthly report.
• Browse the absence-types, absence-policies and absence-requests reference.