Attendance Devices & Face Recognition

Udyamo HRMS integrates with physical attendance devices (biometric terminals, face recognition cameras) to automate check-in and check-out. The AttendanceDevice model handles device registration and token-based authentication, while the EmployeeFace model stores facial embeddings for face recognition. This chapter covers setting up devices, registering employee faces, and managing the integration.

Prerequisites

Required: Before setting up attendance devices:

  • Shifts must be configured and assigned to employees (see Creating & Assigning Shifts)
  • Attendance policies should be in place (see Attendance Policies & Rules)
  • The physical device must be installed, powered on, and connected to the network
  • You need administrator access to Udyamo HRMS
  1. From the sidebar, click Attendance.
  2. Click Devices from the submenu.
  3. The Devices page displays a list of all registered attendance devices.

Attendance devices list

Understanding the AttendanceDevice Model

Each registered device has the following attributes:

FieldDescriptionExample
NameA descriptive name for the deviceMain Entrance Biometric
TokenA unique authentication token used by the device to communicate with the Udyamo HRMS APId3f1a2b4-e5c6-7890-abcd-ef1234567890
Device TypeThe type of device (biometric, face recognition, card reader)Face Recognition
Location/OfficeThe office or location where the device is installedMumbai HQ — Lobby
StatusActive or InactiveActive
Last SyncTimestamp of the last successful communication with the server2025-06-15 18:30:00

Adding an Attendance Device

Step 1: Open the Add Device Form

  1. On the Devices page, click Add Device or Register New Device.
  2. The device registration form opens.

Step 2: Enter Device Details

  1. Name — Enter a descriptive name that identifies the device and its location (e.g., "Ground Floor Biometric", "Cafeteria Face Scanner").
  2. Device Type — Select the type:
    • Biometric (Fingerprint) — Fingerprint scanner
    • Face Recognition — Camera-based facial recognition
    • Card Reader — RFID or proximity card reader
    • Multi-Modal — Device supporting multiple methods
  3. Office — Select the office where the device is installed.
  4. Description — Optional notes about the device (model number, serial number, placement details).

Step 3: Generate the Authentication Token

  1. Click Generate Token or the token is auto-generated upon saving.
  2. The system creates a unique, cryptographically secure token.
  3. This token will be configured on the physical device to authenticate API requests.

Warning: The token is displayed only once when generated. Copy it immediately and store it securely. If you lose the token, you will need to regenerate it, which invalidates the previous token.

Step 4: Save the Device

  1. Click Save.
  2. The device appears in the Devices list with an Active status.
  3. Copy the generated token for device configuration.

Device registration with token

Configuring the Physical Device

After registering the device in Udyamo HRMS, configure the physical device to communicate with the API.

Device Configuration Requirements

SettingValue
API EndpointYour Udyamo HRMS attendance API URL (e.g., https://yourcompany.udyamo.com/api/attendance)
Authentication TokenThe token generated in the previous step
Authentication MethodToken-based (Bearer token in HTTP header)
Data FormatJSON
Sync IntervalHow often the device pushes data to the server (typically real-time or every 1-5 minutes)

How Token-Based Authentication Works

  1. The physical device sends an HTTP request to the Udyamo HRMS API.
  2. The request includes the token in the Authorization header: Bearer <token>.
  3. The server validates the token against the registered AttendanceDevice records.
  4. If valid, the attendance data (employee identifier, timestamp, event type) is accepted and processed.
  5. If invalid, the request is rejected with a 401 Unauthorized response.

Tip: Work with your device vendor to configure the API endpoint and token. Most modern biometric and face recognition devices support REST API integration with custom headers.

API Request Format

The device sends attendance events in the following format:

FieldDescriptionExample
employee_identifierThe employee ID or face recognition match IDEMP-001
timestampThe date and time of the event (ISO 8601)2025-06-15T09:03:00+05:30
event_typeThe type of eventcheck_in or check_out
device_idThe device's registered name or IDmain-entrance

Face Recognition Setup

Face recognition uses the EmployeeFace model to store facial embeddings (mathematical representations of facial features) for each employee. When a face recognition device scans an employee, it generates embeddings and matches them against stored data.

How Facial Recognition Works

  1. Enrollment — The employee's face is scanned and converted into a numerical embedding (a vector of numbers representing facial features).
  2. Storage — The embedding is stored in the EmployeeFace model associated with the employee record.
  3. Recognition — When the device scans a face, it generates a real-time embedding and compares it against all stored embeddings.
  4. Match — If the similarity score exceeds the configured threshold, the employee is identified and the attendance event is recorded.
  5. Logging — An AttendanceEvent of type device_check_in is created with the employee, timestamp, and device information.

Registering Employee Faces

Step 1: Navigate to Face Registration

  1. Open the employee's profile.
  2. Navigate to the Attendance or Face Recognition section.
  3. Click Register Face.

Alternatively:

  1. Navigate to Attendance > Devices > Face Registration.
  2. Select the employee from the dropdown.

Step 2: Capture Face Images

  1. The system prompts the employee to face the camera (web camera or connected device camera).
  2. Capture multiple images (typically 3-5) from slightly different angles for better accuracy:
    • Front facing
    • Slight left turn
    • Slight right turn
    • Slight upward tilt
    • Slight downward tilt
  3. Each image is processed to extract facial embeddings.

Face registration capture screen

Step 3: Review and Save

  1. The system displays the captured images with quality indicators (good, poor, retake needed).
  2. Review the captures. Retake any images marked as poor quality.
  3. Click Save to store the facial embeddings.
  4. The EmployeeFace record is created for the employee.

Tip: For best recognition accuracy:

  • Ensure good, even lighting during enrollment
  • Remove hats, scarves, or other face-covering accessories
  • Ask the employee to maintain a neutral expression
  • Capture in the same lighting conditions as the device location if possible

Face Registration Best Practices

PracticeReason
Register faces in the actual device environmentMatching lighting conditions improves accuracy
Update face data annuallyAppearance changes over time can degrade matching accuracy
Register faces for all shiftsDifferent lighting conditions in day vs. night shifts
Test after registrationHave the employee attempt a check-in to verify recognition works

Managing Employee Face Data

Viewing Registered Faces

  1. Open the employee's profile.
  2. Navigate to the Face Recognition section.
  3. View the registration status: Registered or Not Registered.
  4. If registered, the date of registration and number of stored embeddings are displayed.

Updating Face Data

If an employee's appearance has changed significantly (new glasses, major hairstyle change, weight change):

  1. Open the employee's profile.
  2. Navigate to Face Recognition.
  3. Click Update Face Data or Re-Register.
  4. Capture new images following the same process as initial registration.
  5. The new embeddings replace the old ones.

Deleting Face Data

  1. Open the employee's profile.
  2. Navigate to Face Recognition.
  3. Click Delete Face Data.
  4. Confirm the deletion.
  5. The employee will no longer be recognized by face recognition devices and must use an alternative check-in method.

Warning: Deleting face data is irreversible. The employee will need to go through the full registration process again.

Device Management

Viewing Device Status

The Devices list page shows:

ColumnDescription
Device NameThe registered name
TypeBiometric, Face Recognition, Card Reader
OfficeAssigned office location
StatusActive or Inactive
Last SyncWhen the device last communicated with the server
Attendance Count (Today)Number of attendance events recorded today

Monitoring Device Health

Regularly check the Last Sync timestamp for each device. If a device has not synced recently, it may indicate:

  • Network connectivity issues
  • Device hardware failure
  • API configuration problems
  • Token expiry or invalidation

Tip: Set up monitoring alerts if a device has not synced within a configurable period (e.g., 1 hour during business hours). This allows proactive troubleshooting before attendance gaps accumulate.

Deactivating a Device

  1. On the Devices list, click the Actions menu for the device.
  2. Select Deactivate.
  3. The device status changes to Inactive.
  4. The device's token is still valid but the server rejects attendance data from inactive devices.

Reactivating a Device

  1. Click the Actions menu for the inactive device.
  2. Select Activate.
  3. The device status changes to Active and it can resume sending attendance data.

Regenerating a Token

If a device's token is compromised or lost:

  1. Click the device name to open its details.
  2. Click Regenerate Token.
  3. Confirm the action. The previous token is immediately invalidated.
  4. Copy the new token and reconfigure the physical device.

Warning: Regenerating a token immediately invalidates the previous token. The physical device will stop working until it is reconfigured with the new token.

Troubleshooting

ProblemPossible CauseSolution
Device not syncingNetwork connectivity issueCheck the device's network connection; verify it can reach the API endpoint
"401 Unauthorized" errors in device logsInvalid or expired tokenRegenerate the token in Udyamo HRMS and reconfigure the device
Face recognition not matching employeesPoor lighting during enrollmentRe-register faces in conditions matching the device's environment
Face recognition not matching employeesOutdated face dataUpdate face registration for affected employees
High false-rejection rateRecognition threshold set too highContact your device vendor to adjust the matching sensitivity
High false-acceptance rateRecognition threshold set too lowContact your device vendor to increase the matching sensitivity
Duplicate attendance entriesDevice sending duplicate eventsCheck device sync interval; implement deduplication on the API side
Device registered but no data coming throughAPI endpoint misconfigured on the deviceVerify the URL, token, and data format on the device
Attendance recorded but employee not matchedEmployee identifier mismatch between device and HRMSEnsure the employee ID on the device matches the Employee ID in Udyamo HRMS

Security Considerations

ConsiderationRecommendation
Token storageStore device tokens securely. Do not share via email or messaging.
Face data privacyFacial embeddings are mathematical representations, not actual photographs. Communicate this to employees for privacy concerns.
Data in transitEnsure the API endpoint uses HTTPS to encrypt data between the device and server.
Physical device securityInstall devices in tamper-resistant enclosures. Restrict physical access to device configuration menus.
Employee consentObtain written consent from employees before collecting biometric or facial data, as required by applicable privacy laws.

Warning: Indian data protection regulations may require explicit employee consent for collecting biometric data (fingerprints, facial data). Consult your legal team before enabling biometric or face recognition attendance.

Next Steps