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

# Attendance

> Send clock-ins from biometric clocks or apps and query them

**Required permission:** `hr.attendances`

Recorded attendance feeds payroll: when you generate it, the manager reviews the absences and overtime detected and decides which ones to apply.

## Send clock-ins

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

Records up to **500 clock-ins** per request. Each record is one employee on one day.

```json theme={null}
{
  "records": [
    { "document_number": "01234567-8", "date": "2026-10-01", "check_in": "08:02", "check_out": "17:05" },
    { "employee_id": "uuid", "date": "2026-10-01", "check_in": "07:55", "check_out": "18:30", "notes": "Cierre de mes" },
    { "document_number": "98765432-1", "date": "2026-10-01", "check_in": "08:10" },
    { "document_number": "45678912-3", "date": "2026-10-01", "check_in_at": "2026-10-01 22:00", "check_out_at": "2026-10-02 06:05" },
    {
      "document_number": "11223344-5",
      "date": "2026-10-01",
      "punches": [
        { "type": "in", "at": "2026-10-01 08:00" },
        { "type": "out", "at": "2026-10-01 12:00" },
        { "type": "in", "at": "2026-10-01 13:00" },
        { "type": "out", "at": "2026-10-01 17:02" }
      ]
    }
  ]
}
```

Each record supports **one** of these time formats:

| Format | Use |
| - | - |
| `check_in` / `check_out` | `HH:MM` time on the same day. The check-out must be later than the check-in. |
| `check_in_at` / `check_out_at` | Date and time `YYYY-MM-DD HH:MM`. Allows shifts that **end the next day**. |
| `punches` | List of individual clock punches, each with `type` (`in` or `out`) and `at` (`YYYY-MM-DD HH:MM`). Ideal for lunch breaks and split shifts. |

| Field | Required | Description |
| - | - | - |
| `employee_id` | One of the two | Employee ID in FileXpress. |
| `document_number` | One of the two | Employee's document number (hyphens and spaces are ignored). Ideal for biometric clocks. |
| `date` | Yes | Date (`YYYY-MM-DD`). |
| `check_in` | No | Check-in time (`HH:MM`, 24 h). |
| `check_out` | No | Check-out time. Must be later than the check-in; for shifts that cross midnight use `check_out_at`. |
| `check_in_at` | No | Check-in with date (`YYYY-MM-DD HH:MM`). Must be on the same day as `date`. |
| `check_out_at` | No | Check-out with date (`YYYY-MM-DD HH:MM`). Later than the check-in and at most 24 h after it. |
| `punches` | No | Up to 20 punches, each with `type` (`in` or `out`) and `at` (`YYYY-MM-DD HH:MM`). |
| `notes` | No | Remarks (max. 500 characters). |

**Behavior**

* **Idempotent**: if a record already exists for the employee on that date, it is updated. Resending the same batch does not create duplicates.
* You can send the check-in first and the check-out of the same day later: omitted fields keep their previous value.
* Each record is processed separately: an error does not stop the rest of the batch.
* If you send `check_in_at`/`check_out_at` or `punches`, they take priority over `check_in`/`check_out`. `date` is the day the shift **starts**.
* With `punches`, the day's check-in is the first `in` punch and the check-out is the last `out`; gaps between an out and the next in count as break time. Punches are stored individually and resending them does not duplicate them.
* Each clock-in recalculates the [day's result](https://docs.filexpress.app/en/docs/api/rrhh/resultados-asistencia.md) (tardiness, overtime, etc.).

**`200` response**

```json theme={null}
{
  "status": true,
  "data": {
    "created": 2,
    "updated": 0,
    "failed": 1,
    "results": [
      { "index": 0, "status": "created", "id": "uuid", "employee_id": "uuid" },
      { "index": 1, "status": "created", "id": "uuid", "employee_id": "uuid" },
      { "index": 2, "status": "error", "message": "Employee not found (send a valid employee_id or document_number)." }
    ]
  }
}
```

`index` corresponds to the position of the record in `records`. If **all** records fail, the response has code `422`.

## Query attendance

```http theme={null}
GET /hr/attendances?start_date=2026-10-01&end_date=2026-10-15
```

| Parameter | Required | Description |
| - | - | - |
| `start_date` | Yes | Start date. |
| `end_date` | Yes | End date (maximum range of 93 days). |
| `employee_id` | No | Filter by employee. |

```json theme={null}
{
  "status": true,
  "data": [
    {
      "id": "uuid",
      "employee_id": "uuid",
      "employee_name": "María López",
      "document_number": "01234567-8",
      "date": "2026-10-01",
      "check_in": "08:02",
      "check_out": "17:05",
      "check_in_at": "2026-10-01 08:02",
      "check_out_at": "2026-10-01 17:05",
      "notes": null
    }
  ]
}
```

`check_in_at` and `check_out_at` are `null` on older records that only have a time. For night shifts, `check_out_at` shows the actual check-out date.

For schedule compliance and the classified hours of each day, see [Attendance results](https://docs.filexpress.app/en/docs/api/rrhh/resultados-asistencia.md).


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