Biometric Device Integration with Zoho People: Proven Setup Guide 2026

Every day your HR team manually exports attendance from a biometric device and uploads it to Zoho People, you are paying for a problem that should not exist. Biometric device integration with Zoho People eliminates this — connecting your eSSL, ZKTeco, Biomax, or Matrix attendance machine directly to Zoho People so every punch-in and punch-out syncs automatically, every 5 minutes, without a single manual step. This guide covers the complete setup process for both the Plugin method and API method — including OAuth token generation, the exact SQL database column mapping for each device brand, employee ID mismatch handling, shift configuration, and the troubleshooting steps for every common error. This is the guide that saves your HR team 45 minutes of daily manual work and eliminates payroll errors caused by attendance data gaps.

1. Plugin Method vs API Method — Which One Should Your Business Use?

Zoho People supports two methods for biometric device integration with Zoho People. Choosing the wrong method creates configuration problems that are expensive to fix. Here is the honest decision guide.

2. Supported Biometric Brands — eSSL, ZKTeco, Biomax, and Matrix

The biometric device integration with Zoho People supports all major Indian market biometric brands as long as the device stores attendance data in a local database accessible on the network. Here is what each brand’s integration looks like in practice.

3. Zoho People Plan Requirement for Biometric Integration

This is the most commonly missed prerequisite — and the most expensive mistake. Biometric device integration with Zoho People requires the Premium plan or above. The Essential HR and Standard plans do not include the Attendance module API access that the biometric integration depends on.

4. OAuth Token Generation — The Critical Step Most Guides Skip

The OAuth token is the security credential that allows your biometric device plugin to authenticate with Zoho People and push attendance data. Access Tokens expire every hour — which is why you need a Refresh Token that regenerates them automatically. Here is the exact process.

ZohoPeople.attendance.ALL

POST https://accounts.zoho.in/oauth/v2/token
?grant_type=authorization_code
&client_id=YOUR_CLIENT_ID
&client_secret=YOUR_CLIENT_SECRET
&redirect_uri=https://www.zoho.com
&code=YOUR_AUTHORIZATION_CODE

5. Plugin Method Setup — Complete Step-by-Step Guide

C:\Apache Tomcat\webapps\ZAttendance.war

Client ID: [Your Zoho OAuth Client ID]
Client Secret: [Your Zoho OAuth Client Secret]
Refresh Token: [Your Zoho OAuth Refresh Token]
Organisation: [Your Zoho People Organisation ID]
Data Centre: IN (for zoho.in accounts) or US (for zoho.com)

Database Type: MS SQL Server
Server: 192.168.1.100\SQLEXPRESS
Database Name: ETimetrackliteV2
Username: sa
Password: [your SQL password]
Sync Interval: 5 minutes

SELECT
  EMPCode AS EmployeeId,
  CONVERT(VARCHAR(10), PUNCH_DATE, 23) AS EventDate,
  PUNCH_TIME AS EventTime,
  CASE PUNCH_TYPE WHEN 1 THEN 1 ELSE 0 END AS IsCheckin,
  GETDATE() AS DownloadDate
FROM
  DeviceLogs
WHERE
  DownloadDate >= DATEADD(MINUTE, -10, GETDATE())

{
  "status": "success",
  "message": "Attendance data synced successfully",
  "records_processed": 2,
  "records_failed": 0
}

6. Database Column Mapping — Brand-by-Brand SQL Query Guide

Zoho People’s biometric plugin expects four specific data fields from your biometric database. Every brand uses different column names. Here is the exact mapping for each major brand.

SELECT
  EMPCode AS EmployeeId,
  CAST(PUNCH_DATE AS DATE) 
    AS EventDate,
  PUNCH_TIME AS EventTime,
  CASE WHEN PUNCH_TYPE = 1 
    THEN 1 ELSE 0 END AS IsCheckin
FROM DeviceLogs
WHERE
  DownloadDate > [LastSyncTime]

SELECT
  User_ID AS EmployeeId,
  DATE(Punch_DateTime) AS EventDate,
  TIME(Punch_DateTime) AS EventTime,
  CASE WHEN Punch_State = 0 
    THEN 1 ELSE 0 END AS IsCheckin
FROM att_punches
WHERE
  Punch_DateTime > [LastSyncTime]

SELECT
  EmployeeID AS EmployeeId,
  CAST(AttendDateTime AS DATE) 
    AS EventDate,
  CAST(AttendDateTime AS TIME) 
    AS EventTime,
  CASE WHEN InOut = 1 
    THEN 1 ELSE 0 END AS IsCheckin
FROM DeviceLogs
WHERE
  AttendDateTime > [LastSyncTime]

SELECT
  EnrollCode AS EmployeeId,
  CAST(EventDateTime AS DATE) 
    AS EventDate,
  CAST(EventDateTime AS TIME) 
    AS EventTime,
  CASE WHEN Direction = 'IN' 
    THEN 1 ELSE 0 END AS IsCheckin
FROM AccessEvents
WHERE
  EventDateTime > [LastSyncTime]

7. Employee ID Mapping and Shift Configuration — Two Steps That Break Every Integration

After OAuth and database configuration, these two steps cause the most post-go-live problems in biometric device integration with Zoho People. Both must be completed before the first attendance sync runs.

Employee ID Mapping — When Biometric IDs Don’t Match Zoho People IDs

Most organisations use different ID formats in their biometric devices and in Zoho People. The biometric device might use numeric IDs (001, 002, 003) while Zoho People uses employee codes (EMP001, EMP002). Without mapping, synced data lands in Zoho People without matching any employee — silently failing.

Shift Configuration — Why Wrong Shifts Mean Wrong Payroll

Zoho People calculates attendance (Present, Absent, Half Day, Late) by comparing biometric punch-in/punch-out times against the employee’s assigned shift. If shifts are not configured, or employees are assigned to the wrong shift, biometric data will sync successfully but generate incorrect attendance records.

8. Troubleshooting Common Biometric Integration Errors

These are the five most common errors in biometric device integration with Zoho People — with the exact cause and fix for each.

9. Zoho Payroll Impact — Why Correct Biometric Integration Is a Payroll Compliance Requirement

This section is missing from every competitor’s content — and it is the most important reason to get biometric device integration with Zoho People right the first time.

10. Biometric Device Integration with Zoho People — 8 Questions Answered

Which Zoho People plans support biometric device integration?

Biometric device integration with Zoho People requires the Premium plan (₹144/user/month) or Enterprise plan (₹192/user/month). The Essential HR plan (₹48/user/month) and Professional plan (₹96/user/month) do not include the Attendance API access needed for biometric integration. Verify your current plan at Settings → Subscription in Zoho People before starting setup.

Which biometric device brands work with Zoho People?

Zoho People biometric integration works with eSSL (ETimetracklite software), ZKTeco (ZKBio X software), Biomax, Matrix (COSEC software), and most other brands that store attendance in a local MS SQL, MySQL, or MS Access database. Fingerprint, face recognition, and RFID card devices from these brands are all compatible. Cloud-only devices without accessible local database storage require the API method with the device’s own cloud API.

How often does biometric attendance sync with Zoho People?

Using the Plugin method (ZAttendance on Tomcat), biometric attendance syncs automatically every 5 minutes. The sync interval is configurable — 5 minutes is the default and recommended setting for most businesses. For large databases with 1,000+ employee records, increasing to 10 minutes prevents database query timeout. Using the API method, sync frequency depends on how often your custom script runs — typically every 15-30 minutes for manually scheduled scripts.

Can I integrate biometric devices from multiple locations with one Zoho People account?

Yes. Zoho People supports multi-location biometric integration. For the Plugin method, deploy one ZAttendance plugin instance per location — each connects to that location’s biometric database and pushes to the same Zoho People organisation. For the API method, a centralised script can pull from multiple databases and push all data to one Zoho People API endpoint. Employee work locations in Zoho People determine which shift and attendance policy applies to each employee’s synced records.

What happens if the sync breaks and attendance data is missed?

If the biometric sync stops for any reason — server restart, Refresh Token expiry, network issue — attendance data from the gap period is not automatically backfilled. You must manually upload the missed attendance records using Zoho People’s manual attendance import. The plugin does not look back further than the configured sync window. This is why monitoring the sync status daily and setting up a server alert for Tomcat service failures is recommended for production deployments.

Official Resources — Zoho People Biometric Integration

• Zoho People Official — Biometric Integration Setup Guide
• Zoho API Console India — Generate OAuth Credentials (zoho.in accounts)
• Zoho People Attendance Module — Complete Help Documentation
• Zoho People India Pricing — All Plans (Essential to Enterprise)
• Book Free Consultation — Codroid Labs Zoho Biometric Integration