How to Connect and Manage Biometric Devices in CrmLeaf
All editions. Requires the Biometric add-on module to be enabled for your account by an Administrator, plus the manage_biometric_settings permission. In the Payroll & HR edition the feature is reached from a…
Availability: All editions. Requires the Biometric add-on module to be enabled for your account by an Administrator, plus the manage_biometric_settings permission. In the Payroll & HR edition the feature is reached from a dedicated Biometrics menu group. Core attendance already covers clock-in with geolocation and QR code; the Biometric module is what drives physical hardware.
Overview
The Biometric module connects physical fingerprint and card devices to CrmLeaf so that punches recorded at a device become attendance data in the platform. It is used where attendance must be captured at a fixed entry point rather than from a browser or a phone. Attendance captured this way feeds payroll in the same way as any other attendance record.
What's New NEW
R26.09 · Sep 2026BioMax device support has shipped alongside the existing ZKTeco integration. A company now chooses which hardware protocol it connects — ZKTeco or BioMax — and BioMax devices reach CrmLeaf over a webhook rather than the ZKTeco push protocol, with their own token-based authentication and their own punch log for troubleshooting.
How It Works
CrmLeaf supports two device protocols, chosen per company: ZKTeco, using the ADMS "iclock" push protocol, and BioMax, using a token-authenticated push webhook. Whichever protocol a company selects, the device pushes its data to CrmLeaf; only ZKTeco supports CrmLeaf queuing commands back to the device.
Enable module → Choose device protocol → Register device → Enrol employees → Device pushes punches → Attendance and payroll
- The device protocol is chosen per company: ZKTeco or BioMax. ZKTeco uses the ADMS "iclock" push protocol described below. BioMax instead uses a dedicated push webhook: a Biometric Connection settings page generates a per-company bearer token and webhook URL, and the BioMax device posts each punch as JSON to that webhook, authenticated by the token.
- BioMax punches are matched by employee code, with the device's timestamp converted to the account's timezone, duplicate punches filtered out, and clock-in versus clock-out inferred automatically before the attendance record is written — the same way a ZKTeco punch ultimately becomes an attendance record.
- A BioMax punch log records every punch the webhook receives, tagged processed, skipped, failed or unmapped, so a missing punch can be traced without contacting support.
- Devices shows the registered devices and their device status.
- Device Employees covers enrolled templates along with card and photo data.
- Attendance holds the device punches, each of which can carry a captured photo.
- Commands holds commands queued to a device, which the device collects when it communicates with CrmLeaf. This applies to ZKTeco; BioMax is receive-only from CrmLeaf's side.
- Recent activity shows recent device communication, which is the first place to look when a device appears silent.
- A
force_biometric_clockinoption exists, so an organisation can require clock-in through the device.
Who Can Use This Feature?
Administrator
- Register and monitor biometric devices.
- Manage device employees, enrolled templates, card and photo data.
- Review device punches and recent device activity.
- Queue commands to a device.
- Enable the option that requires clock-in through a biometric device.
This functionality is available only to Administrators, and requires the manage_biometric_settings permission in addition to the Biometric module.
Prerequisites
- The Biometric add-on module enabled for your account.
- The
manage_biometric_settingspermission on your role. - A biometric device that supports one of the two protocols CrmLeaf integrates: ZKTeco's ADMS "iclock" push protocol, or BioMax's push webhook.
- Employee records created in CrmLeaf before enrolment, so punches can be matched to employees.
- Attendance and shift configuration completed, since device punches are interpreted against the assigned shift.
- Network access from the device to CrmLeaf, arranged with your IT team.
For Administrators
Step 1: Confirm the module and permission
What to do: Confirm the Biometric module is enabled for the account, and that your role holds manage_biometric_settings.
What to verify: The Biometrics menu group is visible. Without both the module and the permission, the screens do not appear.
Step 2: Choose the device protocol and register the device
What to do: Decide whether your hardware is ZKTeco or BioMax; the two are not mixed within the same setup. For a ZKTeco device, Add it in Devices so CrmLeaf recognises it, then configure the device itself to push to CrmLeaf using the ADMS "iclock" protocol. For a BioMax device, open Biometric Connection to generate your account's bearer token and webhook URL, then enter both into the device's own configuration so it can post punches to CrmLeaf. Device-side configuration is done on the device or in its own utility, following the manufacturer's instructions either way.
What to verify: A ZKTeco device appears in Devices with a device status showing it is communicating; a BioMax device's punches begin appearing in Attendance, and its activity is traceable in the BioMax punch log.
Step 3: Enrol employees on the device
What to do: Match device users to CrmLeaf employee records and review the enrolled templates, card data and photo held for each.
What to verify: Every employee expected to clock in at the device is enrolled and linked to the correct employee record.
Step 4: Check punches are arriving
What to do: Have an enrolled employee punch at the device, then confirm the punch appears. Each punch can carry a photo captured at the device.
What to verify: The punch appears against the correct employee, with the expected date and time.
Step 5: Use device commands and recent activity
What to do: For a ZKTeco device, queue a command when you need it to act; commands are collected by the device when it next communicates. Use Biometrics → Recent activity to see whether the device has been in contact. BioMax has no command queue — it only pushes punches to CrmLeaf — so check its own punch log instead of Recent activity if a BioMax device seems silent.
What to verify: For ZKTeco, a queued command is collected, confirming two-way communication rather than only inbound punches. For BioMax, recent punches appear in its punch log with a processed status.
Step 6: Decide whether to require biometric clock-in
What to do: Where your policy requires attendance to be captured only at a device, enable the force_biometric_clockin option.
What to verify: Test the effect on employees who work away from the device before applying this to everyone.
Step 7: Confirm attendance flows into payroll
What to do: Before the first payroll run using device data, confirm the resulting attendance records for a sample of employees, then generate and review payroll for one department.
What to verify: Paid days on the payslips match the attendance derived from device punches.
Expected Result
The biometric device is registered and communicating, employees are enrolled, punches arrive in Attendance under the Biometrics group, and the resulting attendance is available to payroll.
Important Notes
- Menu names and their position can differ between product editions and can be customised for your account, so your sidebar may not match these paths exactly. Use Search or your Quick Access items if you cannot find a screen.
- Biometric is a paid add-on module. Confirm it is included in your plan, and note that the
manage_biometric_settingspermission is required in addition to the module. - Device support is documented for two protocols: the ZKTeco ADMS "iclock" push protocol, and the BioMax push webhook. Confirm which one your hardware uses before purchasing.
- A BioMax device authenticates with a bearer token issued on the Biometric Connection page. Treat that token like a credential — anyone who has it can post punches to your account.
- Biometric templates and captured photos are personal data. Confirm your legal basis for collecting them, your retention position and your employee notification obligations with a qualified advisor before deployment.
- Enabling
force_biometric_clockinaffects everyone it applies to. Consider employees who work remotely or in the field, since core attendance also supports geolocation and QR code clock-in. - Attendance affects pay. Confirm that device attendance is complete for a period before payroll is generated.
Common Scenarios
Example: a factory entry point. A manufacturer installs a device at the entrance, enrols shop-floor employees, and relies on device punches for their attendance, while office staff continue to clock in through core attendance.
Example: a device stops reporting. Payroll notices missing attendance. The Administrator checks Recent activity, finds no recent communication from the device, and works with the IT team on network access before payroll is generated.
Example: mixed workforce. An organisation enables the option to require biometric clock-in for site-based teams only, after testing it, so field employees are not blocked from recording attendance.
Troubleshooting
| Issue | Possible Cause | Resolution |
|---|---|---|
| The Biometrics menu group is not visible | The Biometric module is not enabled, or the role lacks manage_biometric_settings | Enable the module for the account and grant the permission to the role. |
| The device does not appear to be communicating | The device cannot reach CrmLeaf, or its push configuration is incomplete | For ZKTeco, check Recent activity; for BioMax, check its punch log. Then confirm the device's network access and, for BioMax, that it is using the current bearer token and webhook URL. |
| Punches arrive but are not linked to an employee | The device user is not matched to a CrmLeaf employee record | For ZKTeco, link the device user in Device Employees. For BioMax, confirm the device is sending the correct employee code; an unmatched punch logs as unmapped. |
A BioMax punch is logged as failed or skipped | The webhook rejected the punch (bad token or malformed payload), or it was recognised as a duplicate | Check the punch log's reason. Regenerate the bearer token if it may be wrong, and confirm the device's clock and payload format with its vendor. |
| A queued command is not carried out | The device has not yet communicated to collect it, or the device is BioMax, which has no command queue | For ZKTeco, confirm the device is online in Recent activity, then check the command again. Commands do not apply to BioMax. |
| Attendance from the device is missing on payslips | Punches for the period arrived after payroll was generated | Confirm attendance for the period is complete, then generate payroll again. |
Frequently Asked Questions
Which devices are supported?
Two protocols: ZKTeco, using the ADMS "iclock" push protocol, and BioMax, using a token-authenticated push webhook. Confirm a specific model against one of these two with your Administrator before purchase.
Can I mix ZKTeco and BioMax devices on the same account?
No. The device protocol is a single, account-wide choice — ZKTeco or BioMax — not a per-device setting.
Do I need the Biometric module for GPS or selfie attendance?
No. Core attendance handles clock-in with geolocation and work-from options, and the mobile app supports face and location verification. The Biometric module drives hardware devices.
Can I require employees to clock in only at a device?
Yes. A force_biometric_clockin option exists. Test its effect on remote and field employees first.
Are photos captured with punches?
A device punch can carry a captured photo, and enrolled device employee data can include a photo. Treat these as personal data.
Where do biometric punches end up?
In attendance, which is what payroll calculates paid days from.