---
title: "4.0 Configuration"
space: "ZKTeco Biometric Integration for FrappeHR"
url: "https://docs.navari.co.ke/zkteco/50-configuration"
updated: "2026-05-24"
---

### 4.1 ZKTeco Device Setup

Before configuring the integration, verify the following on the physical device:

- The device is powered on and connected to the same network (or a routable network) as the Frappe server.
- The device's IP address is static or reserved via DHCP, so it does not change between syncs.
- The device's admin username and password are known.
- The REST API (ICLOCK interface) is enabled on the device. Most ZKTeco devices running firmware version 6.60 and above expose this by default.
- Ports are open: test reachability with `curl http://{device_ip}/iclock/api/transactions/` from the Frappe server before proceeding.

### 4.2 ZKTeco Biometric Settings Doctype

Navigate to: **ZKTeco Biometric Integration > ZKTeco Biometric Settings**

![](/files/image00f4e8.png)
*ZKTeco Biometric Settings*

Each settings document represents one ZKTeco device. You can create multiple settings documents to manage multiple devices.


| Field               | Description                                                                       | Example                |
| ------------------- | --------------------------------------------------------------------------------- | ---------------------- |
| **Username**        | Admin username for the ZKTeco device. Must be unique per device.                  | `admin`                |
| **Password**        | Admin password for the ZKTeco device.                                             | `Admin1234`            |
| **URL**             | Base URL of the device, including scheme and IP. Do not include a trailing slash. | `http://192.168.1.100` |
| **Fetch Frequency** | How often the scheduler pulls data from this device. See options below.           | `Hourly`               |
| **Enable**          | Toggle to activate or pause this integration without deleting the settings.       | Checked                |


**Fetch Frequency options:**


| Option           | Behaviour                                                                                              |
| ---------------- | ------------------------------------------------------------------------------------------------------ |
| All (Continuous) | Runs on every scheduler tick (approximately every minute). Use with caution on large deployments.      |
| Hourly           | Runs once per hour.                                                                                    |
| Daily            | Runs once per day.                                                                                     |
| Weekly           | Runs once per week.                                                                                    |
| Monthly          | Runs once per month.                                                                                   |
| Custom Cron      | Accepts a standard cron expression for precise scheduling (e.g., `*/15 * * * *` for every 15 minutes). |


### 4.3 JWT Token Management

Saving the `ZKTeco Biometric Settings` document triggers automatic token generation. The system:

1. POSTs the configured credentials to the device's auth endpoint.
2. Stores the returned JWT token internally.
3. Includes the token in the `Authorization: JWT <token>` header on all subsequent requests.
4. Detects `401 Unauthorized` responses and re-authenticates transparently before retrying.

You do not need to manually manage tokens. If authentication fails persistently, re-save the settings document to trigger a fresh token request, and verify credentials are correct.



### 4.4 Employee Biometric ID Mapping

Each employee in FrappeHR must have their Biometric ID set to the ID registered for them on the ZKTeco device.

1. Open the **Employee** master record.
2. Locate the **Biometric ID** field (under the Attendance section, or as a custom field depending on your HR configuration).
3. Enter the exact numeric or alphanumeric ID that matches what the device records in the `emp_code` field of its punch transaction log.

Requirements:

- The Biometric ID must be unique across all employee records.
- It must match exactly no leading/trailing spaces, no formatting differences.
- If an employee is registered on multiple devices, the same Biometric ID must be used on all devices.



If an employee's Biometric ID is missing or does not match any punch record's `emp_code`, that employee's punches will be silently skipped. Check the Error Logs for `Employee Not Found` entries to identify mismatches.



### 4.5 Shift Assignment

The FrappeHR attendance processing pipeline (which converts raw Check-in records into Attendance documents) depends on employees having shifts assigned. Assign the appropriate **Shift Type** to each employee under the Employee master or via **Shift Assignment** before expecting attendance to be processed correctly from the synced data. The integration itself creates raw Employee Check-in records; shift resolution is handled downstream by FrappeHR's standard attendance automation.