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

# Register a terminal

> Claim an unregistered device by its serial, and monitor fleet health afterwards.

export const PermissionNote = ({perm}) => <Info>
    Requires the <code>{perm}</code> permission. Ask your administrator if an
    action described here is missing from your screen — see
    [Roles & permissions](/help/concepts/roles-and-permissions).
  </Info>;

<PermissionNote perm="device:write" />

## Devices find you

You do not enter a device's details by hand. Once the connector is running and a terminal has been pointed at it, the device announces itself and appears in OnTime **by serial number**, waiting to be claimed.

<Note>
  **An unregistered serial is handled gracefully.** OnTime records it as an unclaimed device and still returns success to the connector, so the terminal's queue drains rather than backing up behind a rejection. No tenant data is touched until you register it.
</Note>

## Registering

<Steps>
  <Step title="Open Attendance → Devices">
    The **Machines** tab lists registered devices with their status.
  </Step>

  <Step title="Enter the serial, then Verify">
    Match the serial against the physical device — it is printed on the unit. **Verify** tells you what OnTime already knows about it before you commit (see below).
  </Step>

  <Step title="Give it a name and location">
    A readable name such as `Main gate — Pune HQ`, and the location it sits at. The name is what you will see everywhere afterwards; the serial stays underneath as the key OnTime matches on the wire. The location matters for reporting and for the fleet view.
  </Step>

  <Step title="Confirm">
    Registering **adopts** the unclaimed record for that serial: the device becomes yours, and its punches start resolving against your employees.
  </Step>
</Steps>

## Verifying a serial

**Verify** checks the serial against every device that has ever contacted the connector:

| Result                 | Meaning                                                                                                                                          | What to do                                                                                                       |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------- |
| **Seen**               | A terminal with this serial has reached the connector. Shows its type, when it was first and last heard from, and how many messages it has sent. | Go ahead — this is the confident case.                                                                           |
| **Not seen yet**       | No terminal with this serial has ever contacted us.                                                                                              | Check the label for a typo, and that the unit is powered and on the network. You can still register — see below. |
| **Already registered** | Some organization already holds this serial.                                                                                                     | Stop. Check the physical unit; registration is blocked.                                                          |

<Note>
  **"Not seen yet" does not block registration.** It is normal to register a machine before it is plugged in — the usual install order is to set it up in OnTime, then power the unit on site. Verify is there to catch a mistyped serial, not to gate you.
</Note>

<Tip>
  OnTime cannot ping a terminal to check it. Devices dial **out** to the connector; nothing can dial in. So the only honest answer to "is this serial real?" is whether the connector has heard from it — which is exactly what Verify reports.
</Tip>

<Warning>
  **Only register serials you recognise.** The connector is shared, so a serial appearing in your unclaimed list is a device that reached the connector — registering it claims its punches into your organization. Check the physical unit.
</Warning>

## Device details

Each registered device carries:

| Field             | Meaning                                                                                                 |
| ----------------- | ------------------------------------------------------------------------------------------------------- |
| **Name**          | Your label for it, e.g. `Main gate — Pune HQ`. Optional, and editable at any time.                      |
| **Device ID**     | Your business key, e.g. `BIO-MUM-01`.                                                                   |
| **Serial**        | The manufacturer's serial — how OnTime recognises it on the wire. Cannot be changed after registration. |
| **Location**      | Where it is.                                                                                            |
| **Model**         | Reported by the device.                                                                                 |
| **Kind**          | `biometric` or `kiosk`.                                                                                 |
| **Last sync**     | When it last spoke to OnTime.                                                                           |
| **Status**        | `Online` or `Offline`.                                                                                  |
| **Punches today** | Derived.                                                                                                |

## Fleet health

The Devices page carries KPIs across the fleet — total, online, offline, punches today — and the admin dashboard raises an alert for offline devices.

### How Online and Offline are decided

<Note>
  **Terminals report liveness with a keepalive message, and nothing else.** A biometric device that has been silent for **5 minutes** is marked `Offline`. The next keepalive flips it back automatically.

  Kiosk-kind devices are exempt from this watchdog.
</Note>

<Warning>
  **Offline means "has not spoken recently", not "is broken".** A terminal on a network that drops overnight will show offline every night and recover every morning — and, crucially, will not have lost any punches, because they sit in its flash until it can deliver them.

  Investigate an offline device that stays offline, not one that flickers.
</Warning>

## Removing a machine

<PermissionNote perm="device:write" />

**Remove** is in the `⋯` menu on a machine's row. What it does depends on whether the machine has any history:

* **No punches at all** — it is **deleted outright**, and its serial is freed to register again. This is the escape hatch for a typo'd serial.
* **Any punch history** — it is **decommissioned**, not deleted. It disappears from the fleet list and the KPIs, but every punch it ever recorded stays exactly where it is, and the serial stays claimed.

The confirmation dialog tells you which will happen before you commit, and the confirmation message afterwards tells you which actually did.

<Note>
  **Attendance history is never deleted with a machine.** Punches are attendance records in their own right — a payroll cycle that has already used them must keep reading the same numbers. Decommissioning is how a machine leaves the fleet without disturbing them.
</Note>

Decommissioned machines are visible behind **Show retired** on the Devices toolbar, and **Restore** in the same `⋯` menu puts one back in service.

## When a device is replaced

Register the new serial, then remove the old machine — it will be decommissioned rather than deleted, so its historical punches stay attached to it as part of the attendance history.

<Tip>
  Terminal user mappings are keyed on the terminal's user ID, so replacing hardware usually means re-checking mappings against the new device's enrolment numbering. See [Map terminal users](/terminals/map-terminal-users).
</Tip>