How to Connect a ZKTeco or eSSL Biometric Machine to HRMS and Payroll (2026)

If you already own a biometric machine, the question is rarely "which device should we buy?" It is "how do we get these punches into our HR software and payroll without someone downloading a file every month?" Most Indian offices end up with a ZKTeco, eSSL, Realtime or Mantra machine on the wall, a USB stick, and an HR person exporting Excel files before every payroll run. It works, but it is slow, and it breaks whenever someone forgets.

This guide explains the ways to connect a ZKTeco-protocol biometric machine to an HRMS, and walks through the setup step by step using PeopleVio as the example. It also lists what can go wrong and what the integration does not do, so you know before you start.

Menu names on machines differ by model and firmware, so treat the paths below as a guide and check your machine's manual. Machine prices are indicative and vary by dealer.

Which machines can connect

Most fingerprint and face machines sold in India speak the ZKTeco protocol, including ZKTeco, eSSL, Realtime and Mantra devices. What matters for cloud sync is whether your model has a Cloud Server Setting (ADMS) option in its communication menu. If it does, it can push each punch to a server over the internet as it happens.

Older or basic models may only support USB download or a LAN connection. Those can still work, using one of the other two methods below.

The three ways to connect a machine

Method	Best for	How it works
Cloud push (ADMS)	Machines with a Cloud Server Setting	The machine sends each punch live to the HRMS. No PC or software needed at your office
API, webhook or local agent	LAN-only machines, or a vendor cloud you already use	Something sends punches to the HRMS as JSON: a vendor's webhook, or a small script on an office PC that reads the machine
CSV import	Machines with USB export only, or catching up a backlog	You upload the punch log file and map the columns

PeopleVio supports all three, and every source feeds the same attendance pipeline, so you can mix them across branches.

Step-by-step: connecting a machine by cloud push (ADMS)

1. Find the machine's serial number. On the machine, open Menu, then System Info, then Device Info. Copy the serial number exactly.

2. Register the machine in PeopleVio. An admin opens the biometric section in Settings, adds a machine source and enters:

• a name (for example "Head Office Gate")
• the serial number
• how to match employees: by machine user ID, employee code or email
• the UTC offset of the machine's clock in minutes (India is 330)

Machines identify themselves only by serial number and send no login, so a machine that isn't registered is rejected. One physical machine belongs to exactly one company.

3. Point the machine at the server. PeopleVio shows the values to enter. On the machine, go to Menu, then Comm., then Cloud Server Setting (ADMS), and enter the server address and port shown in PeopleVio (port 443 with HTTPS on, or port 80 with HTTPS off). The machine must support HTTPS if the server requires it.

4. Give every employee an ID that matches. The ID a person enrols with on the machine must match what PeopleVio expects: the machine user ID field on the employee, their employee code, or their email. Pick one rule and stick to it.

5. Test it. Punch on the machine. The source shows as online once the machine starts checking in, and it is treated as offline if it stays silent for a few minutes. Open the employee's attendance and confirm the day's record appeared.

How a punch becomes attendance

Understanding the rules avoids surprises at payroll time:

• First punch of the day is check-in, last punch is check-out. Punches in between don't create extra records.
• Double scans are ignored. People often scan twice. Punches within two minutes of each other count as one touch, so a lone check-in doesn't turn into a check-in and check-out.
• Late marks follow your normal rule. A check-in after office start time plus the grace period is marked late, and once the monthly late allowance is used up, the day becomes a half-day, the same policy as an in-app check-in.
• Leave days are protected. A day already marked as leave keeps its status.
• Backlogs are safe. If a machine was offline and uploads a batch later, or resends punches, duplicates are skipped and the result is the same. Order doesn't matter.
• Bad clocks are contained. Punches more than a day in the future are dropped.
• Unknown IDs are recorded, not lost. A punch that doesn't match an employee is logged as unmapped, and punches for inactive employees are not applied.

Because these punches write to the same attendance records as the rest of the product, the monthly payroll run uses them with no extra step: machine to attendance to payroll without an Excel file in between. One thing to decide first: by default payroll deducts pay only for days recorded as Absent or Half Day, so a working day with no punch and no record is not deducted. An admin can switch on the auto-absent setting to count those days as unpaid (weekly offs, holidays, leave and comp-off days are never counted), and reviewing the team attendance grid before payroll is worth doing either way. Our biometric attendance with payroll guide explains the rules.

When the machine can't push: API and local agent

If your machine is on a LAN with no cloud option, a small script on an office PC can read punches from it and send them to PeopleVio. Create an API source in Settings, and PeopleVio shows an API key once. The script sends a request like this:

curl -X POST <endpoint shown in PeopleVio> \
  -H "Authorization: Bearer <your API key>" \
  -H "Content-Type: application/json" \
  -d '{"punches":[{"id":"12","time":"2026-09-21 09:41:07"}]}'

The receiving side accepts the common field names vendors use for "who" (such as id, pin, biometricId, employeeCode, userId or email) and for "when" (such as time, timestamp, punchTime or datetime). Times can be an epoch value, an ISO time with an offset, or a plain date and time read on the machine's clock. Bad rows are rejected with a reason, and the rest go through.

Regenerating an API key invalidates the old one, so rotate it if it is ever shared.

When you only have a file: CSV import

If your machine or its vendor software exports a punch log as CSV, upload it in the import section. You choose which column is the user ID, which is the date (and time), and whether the date order is day-first or month-first, and you see a preview before importing. This is also the fastest way to load a backlog from before you connected the machine.

Troubleshooting

Symptom	Likely cause
Machine never shows online	Wrong server address or port, HTTPS mismatch, or no internet on the machine
"Unregistered device" style rejection	Serial number not registered, or typed with a mistake
Punches arrive but attendance is empty	Employee IDs don't match the "match by" rule, so punches are logged as unmapped
Times are off by hours	Wrong UTC offset on the source; India is 330 minutes
A day shows only a check-in	Only one punch, or two punches within two minutes
Some employees never appear	The employee is inactive, or has no machine ID saved

An honest note on limits

• No shift logic on top of punches. Attendance uses your configured office timing and late grace period. There is no rotating-shift roster or overtime calculation, so overnight shifts that cross midnight are not modelled separately.
• Only first and last punch count. Lunch or break punches are not tracked as separate records.
• Not every machine supports cloud push. Confirm your model has a Cloud Server Setting (ADMS), or plan on the API or CSV route. Test one machine before you buy several.
• Geofencing doesn't apply to machine punches. The machine's location is the location. Geofenced check-in from a phone is a separate option for staff who don't use the machine.
• You buy the hardware separately. PeopleVio is software. Indian price guides typically put basic fingerprint machines at a few thousand rupees and face-recognition devices well above that, so get dealer quotes.
• PF and ESI are not calculated or filed by PeopleVio. See our PF and ESI guide.

If you want more background on choosing between biometric and phone-based attendance, see our biometric attendance software guide and the geofenced attendance guide.

A worked example: a 40-person office with one machine

Suppose a 40-person company has one eSSL machine at the front door and a mix of office and field staff.

• Setup: an admin registers the machine's serial number, chooses to match employees by employee code, and sets the UTC offset to 330. On the machine, they enter the server address and port under Cloud Server Setting (ADMS).
• Enrolment: each office employee is enrolled on the machine with their employee code as the user ID.
• Field staff: the four field employees use geofenced check-in from a phone, while office staff use the machine, both feeding the same attendance calendar.
• Payroll: at month end, one payroll run uses the combined attendance, with no export or upload.
• Cost: at 40 employees the 26 to 100 band applies, ₹49 per employee per month on monthly billing (₹41 on yearly). That is ₹1,960 a month, or ₹1,640 a month billed yearly, with all modules included, plus the machine you already own. The band rate applies to your total active employee count, so check the pricing page for current numbers.

Common mistakes

• Inconsistent IDs. Half the team enrolled by number and half by employee code means half the punches go unmapped. Decide the rule before enrolling anyone.
• Wrong clock or timezone on the machine. Every punch is off by the same amount and late marks go wrong.
• Buying several machines before testing one. Confirm cloud push works on your exact model first.
• Skipping the payroll check. Run one parallel payroll cycle and compare attendance days against your old export.
• Leaving ex-employees enrolled. Deactivate them so their punches don't pile up as noise.

Frequently asked questions

Which biometric machines work with PeopleVio? Machines that use the ZKTeco protocol with Cloud Server (ADMS) push, including ZKTeco, eSSL, Realtime and Mantra devices, plus any system that can send punches through the API or export a CSV. Confirm your specific model in a demo.

Do I need a PC at the office running software? Not for machines with cloud push. The machine sends punches straight to the server. A PC with a small script is only needed for LAN-only machines that can't push.

How do punches reach payroll? Punches update attendance records, and monthly payroll deducts for days recorded as Absent or Half Day, and optionally for working days with no record if the auto-absent setting is on. There is no manual export step, but review the attendance grid before running payroll.

What happens if the internet drops? Machines typically keep punches and send them when they reconnect. PeopleVio skips duplicates and applies the earliest and latest punches for each day, so a backlog produces the same result.

Can we use both the machine and a phone app? Yes. Office staff can use the machine and field or remote staff can use geofenced check-in from a phone browser, both writing to the same attendance calendar.

Does it handle shifts or overtime? No. It uses your configured office timing and late grace period, with no shift roster or overtime rules.

How much does it cost? On PeopleVio, 40 employees falls in the 26 to 100 band at ₹49 per employee per month (₹41 yearly), so about ₹1,960 a month on monthly billing, with biometric connection included. You buy the machine separately.

Can I load old punch data? Yes. Export the log from the machine's software as CSV and use the import to load it, choosing the user ID and date columns.

The bottom line

Connecting a biometric machine to your HRMS should take an afternoon, not a monthly export routine. If your machine supports cloud push, register its serial number, point it at the server, match your employee IDs and it feeds attendance and payroll on its own. If it doesn't, an API script or CSV import gets the same result. Test one machine end to end before you commit, and check every payroll day against your old process for one cycle.

Want to connect your machine? Request a demo and we'll set up a workspace so you can test it with your own device, or check the pricing.