TingPush Camera AI

Integration docs

Face time attendance — a TingPush camera as a time clock

Bản tiếng Việt

A TingPush camera recognises employees' faces on the camera's own chip and records arrival / departure times, like a face time clock. Every successful check-in is sent exactly the way licence plates are sent:

  • Stored on TingPush (hosted storage, default): see who has arrived, monthly timesheets and Excel (CSV) export on the web viewer webrtc.tingpush.com, the TingPush Camera app and the Windows software; HR / payroll software pulls the data through the API.
  • Your own API: the camera sends records straight to your server, to the same URL that receives plates.

Recognition runs on the camera, so attendance keeps working without Internet; records wait in the camera's queue and are sent automatically when the connection returns.

1. Requirements

Needed Notes
A service plan with Attendance Included in the default plan. Retention of attendance records follows the plan (default 400 days).
Camera software with attendance October 2026 or later. Attendance → Settings shows "camera software has no attendance" when the camera needs an update.
Face models on the camera Shipped with the camera software (YuNet face detection, SFace recognition — run on the NPU).
You are the camera owner Only the owner can enable attendance and load employee photos into the camera.

Mounting the camera

  • Put it at an entrance / walkway where people slow down or stop (door, turnstile, reception desk).
  • Mount at 1.6 – 2.2 m, tilted down slightly (≤ 15°) so it sees faces from the front. A camera mounted too high only sees the top of heads.
  • People should stand 1 – 3 m from the camera; the face must be large enough in the picture (by default ≥ 60 pixels wide on the analysis frame).
  • Avoid backlight (glass doors, sun behind people) — dark faces are not recognised. Light the faces at night.
  • A plate-reading camera can be shared if it sees faces clearly, but a dedicated camera at the pedestrian door gives the best results.

2. Registering employees (face photos)

Employees are people in the face library with an extra employee code and department. Add them in:

  • Web: the Nhân viên (Employees) menu (webrtc.tingpush.com/employees).
  • TingPush Camera app: Account → Employees & faces (you can take the photo with the phone).
  • Windows software: the Nhân viên (Employees) page.
  • Your HR software: POST /api/v1/employees (section 7).

Each person needs:

Field Required Notes
Portrait photo ✔ JPEG, max 4 MB. Looking straight, well lit, face filling most of the picture (like an ID photo), no mask / sunglasses.
Full name ✔ Max 60 characters.
Employee code Max 24 characters, unique within the account. Sent with every attendance record (employee_code) to match your payroll software.
Department Filters the timesheet by department.
Cameras Cameras that recognise this person. For a time clock: press Load all to load the whole list into one camera.

After saving, the server sends the photo to each selected camera; the camera computes the face features itself (the photo is not resent for each check-in). Status per camera:

  • green / loaded — the camera has learnt the face.
  • pending — the camera is offline; the server loads it automatically when the camera comes back online.
  • error — usually "no face found in the photo" or a blurred photo → Edit → choose another photo.

Each camera holds up to 3000 people. Changing name / code / department needs no reload; changing the photo reloads it automatically. Deleting an employee: cameras stop recognising them, attendance history is kept.

3. Enabling attendance on a camera

Web: Attendance → Settings tab (app and Windows: Attendance → Shift & cameras). For each camera:

Setting Default Meaning
Enable attendance off The camera starts recognising and recording attendance.
Each person again after 60 seconds Standing in front of the camera records once; walking past again only counts after this time. Use 15–30 minutes if staff often pass the door.
Minimum similarity 42 % Similarity score (cosine × 100) to accept a match. Higher = fewer false matches but people may need to stand longer; lower = faster but more risk of mixing up similar people. Sensible range 38–55.
Attached image face None / face (cropped around the face, ~10–30 KB) / face + full scene. Images help with disputes.

The settings live in the camera's /userdata/lpr/ai.conf (developers / installers):

attendance.enable=1
attendance.cooldown_s=60     ; count again after (seconds)
attendance.confirm=2         ; consecutive frames that must recognise the same person (within 3 seconds)
attendance.min_face=60       ; minimum face width (pixels) — smaller faces are ignored
attendance.image=1           ; 0 no image, 1 face image, 2 face + full scene
attendance.schedule=         ; active hours (empty = all day), same syntax as other AI features
attendance.days=127          ; days of week (bit 0 = Sunday)
face.threshold=42            ; minimum similarity (shared with face recognition)

How the camera records

  1. Detect faces in the frame (up to 3 per frame, largest first).
  2. Skip faces that are turned too far, too small or blurred (quality gate) — avoids false matches.
  3. Compare with the library; the same person ≥ minimum similarity in 2 consecutive frames (default) → check-in.
  4. Write the record to the camera's queue (survives power loss), send it, then block that person for the count again time.

Employees just look at the camera for 1–2 seconds. The camera's local web page (Trạng thái / Status tab) has a Recent attendance card so installers can test on site.

Limitation: the camera does not detect spoofing with a photo / phone screen (no liveness check yet). Place the camera where people are around / covered by CCTV, and check the attached image when in doubt. Masks, sunglasses and low caps reduce recognition.

4. Stored on TingPush — viewing, timesheets, export

The Attendance page (web, app, Windows):

  • Today: who has arrived, in / out times, who is late, who has not checked in — updated as soon as the camera sends.
  • Timesheet: by month / date range, filter by department; per person: workdays credited, hours worked, late / early counts, absent days; click a person to see each day.
  • History: every check-in with the face image, camera and similarity; filter by person.
  • Manual entry: add a check-in when someone forgot / the camera lost power — a reason is required, the record is marked "manual" with the name of who added it.
  • CSV export (opens in Excel, UTF-8 with BOM): timesheet (one row per person per day + a total row) or the list of check-ins.

How workdays are calculated

Set in Attendance → Settings → Shift (one shift for the account):

Setting Default
Shift start / end 08:00 / 17:00 Overnight shifts are fine (e.g. 22:00 → 06:00).
Late / early grace 5 / 5 minutes Within this many minutes still counts as on time.
Break 60 minutes Deducted from hours worked when working more than 5 hours.
Working days Mon – Fri Other days: check-ins are recorded but not counted as late / early / absent.
Workday rollover 04:00 Check-ins before this time count for the previous day (a night shift leaving at 02:00 belongs to the day before).

Within one workday:

  • First check-in = in, last check-in = out (check-ins in between are ignored).
  • Both in and out → 1 workday; a single check-in → ½ workday, status Missing check-out (today: Working).
  • Late = in time − shift start (beyond the grace); early = shift end − out time.
  • A working day with no check-in → Absent.

Need more complex shifts (several shifts, rotations, overtime)? Pull the list of check-ins through the API (section 7) and calculate in your HR software.

5. Sending to your own API

When the camera's Data destination is Own API (app → Camera settings → Plate data), attendance records go to the same URL, with the same auth header, in the same queue as plates — distinguished by "type": "attendance". All rules for replying to the camera (2xx / 4xx / 5xx), de-duplication by event_id, size limits… are exactly as in Writing an API that receives plate reads from TingPush cameras.

{
  "event_id": "LPR-9MHK902C8J5Z-1792114200-000043",
  "type": "attendance",
  "device_id": "OFFICE-DOOR",
  "camera_id": "LPR-9MHK902C8J5Z",
  "time": "2026-10-16T07:58:12+07:00",
  "timestamp": 1792114692,
  "person_id": "22152868dc7d49d4",
  "employee_code": "NV001",
  "name": "Nguyễn Văn A",
  "similarity": 0.713,
  "box": [1610, 520, 1790, 745],
  "frame_width": 3840,
  "frame_height": 2160,
  "face_image_type": "jpeg",
  "face_image": "/9j/4AAQSkZJRgABAQ..."
}
Field Type Always Meaning
event_id string ✔ Unique id of the check-in — UNIQUE key for de-duplication (the camera resends the same id when it gets no reply).
type string ✔ Always "attendance". An API that only handles plates should return 200 and ignore records whose type is not plate (4xx also makes the camera drop it, but the log shows an error).
camera_id, device_id string ✔ As in plate records.
time, timestamp string, int ✔ Check-in time (ISO 8601 with time zone; UNIX seconds — preferred).
person_id string ✔ Employee id assigned by TingPush (unchanged when name / code are edited).
employee_code string ✔ The employee code you set; empty string if not set. Use it to match your HR software.
name string ✔ Full name at check-in time.
similarity number ✔ Similarity 0–1 (≥ the configured threshold).
box int[4] ✔ Face position [x1, y1, x2, y2] on the frame_width × frame_height frame.
face_image string when enabled Face JPEG, base64 (cropped around the face), face_image_type = "jpeg".
image string when enabled Full-scene JPEG, base64, image_type = "jpeg".

Notes:

  • The employee list and photos are still managed on TingPush (cameras download photos from the TingPush server) — only the attendance records go to your API. To sync employees from your HR software use /api/v1/employees (section 7).
  • The camera does not send separate "in" / "out" events — each record is one sighting; choose your own rule (e.g. first = in, last = out, like TingPush).

6. Opening a door on a successful check-in

Peripherals (magnetic door lock, turnstile, buzzer, light) have the trigger Chấm công thành công (attend_ok): Camera settings → Peripherals → Automation rules: When = successful check-in, Then = open the door lock (pulse). Rules run on the camera and work offline. See Peripherals — opening barriers, roller doors, sirens and lights from a TingPush camera.

7. Public API (API key)

Same API key and calling convention as TingPush public API — fetching stored plate data (X-Api-Key: tp_…). Adding / editing / deleting employees needs a key with the "Control devices & edit plate lists" permission.

GET /api/v1/attendance — check-ins

Parameter
since_id Records with id > this value, oldest first — for incremental sync (store next_since_id for the next call).
before_id Next page when browsing newest → oldest.
from, to Time range (ISO 8601).
camera, person Filter by camera / person_id.
limit 1–1000, default 100. 
{
  "data": [
    {
      "id": 1842, "camera_id": "LPR-9MHK902C8J5Z", "camera_name": "Office door", "person_id": "22152868dc7d49d4",
      "employee_code": "NV001", "name": "Nguyễn Văn A", "department": "Accounting",
      "time": "2026-10-16T07:58:12+07:00", "timestamp": 1792114692, "received_at": "2026-10-16T07:58:13+07:00",
      "similarity": 0.713, "source": "camera", "note": null,
      "face_image_url": "https://apiwebrtc.tingpush.com/api/v1/attendance/1842/image/face", "image_url": null
    }
  ],
  "next_since_id": 1842,
  "has_more": false
}

source = camera or manual (manual entry, note is the reason). Images: face_image_url (face), image_url (full scene, when the camera sends it and the plan stores it) = GET /api/v1/attendance/{id}/image/face|scene, downloaded with the same API key header; null = no image.

GET /api/v1/attendance/timesheet?from=2026-10-01&to=2026-10-31&department=… — timesheet

Up to 62 days. Returns shift (shift settings) and data[]: per person person_id, employee_code, name, department, total (credit, late_count, late_min, early_count, early_min, work_min, absent) and days[] (date, first, last, count, late_min, early_min, work_min, credit, status). Status texts are in Vietnamese (Đủ complete, Vắng absent, Nghỉ day off, Muộn N' late, Sớm N' early, Thiếu chấm ra missing check-out).

Employees
GET /api/v1/employees List: id, code, name, department, note, photo_url, cameras[] (id, state = ok / pending / error, message).
GET /api/v1/employees/{id}/photo Registered portrait photo (JPEG).
POST /api/v1/employees Add: {"name":"…","code":"NV002","department":"Warehouse","note":null,"photo":"<JPEG base64>","cameras":["LPR-…"]}.
PUT /api/v1/employees/{id} Edit — send only the fields to change; photo = replace the photo; cameras = reset the camera list.
DELETE /api/v1/employees/{id} Delete (attendance history is kept).

Adding an employee waits for the cameras to load the photo (a few seconds per camera) — check cameras[].state in the result; on error with a message (e.g. no face found) send a different photo.

8. Personal data

Face photos and face features are biometric data — sensitive personal data under Vietnam's personal data protection rules (Decree 13/2023/ND-CP and the Personal Data Protection Law). Businesses using face attendance should:

  • Inform employees and obtain consent before registering photos (e.g. a clause in the contract / a consent form), and offer another way to clock in for those who decline.
  • Use the data only for the announced attendance / access purpose; delete employees when they leave (cameras delete the features immediately).
  • Set a suitable retention period (the plan deletes expired records and images automatically) and limit who can view.

TingPush stores the photos on its server so cameras can download them; face features live only on the cameras. Deleting the account deletes all employees, photos and attendance history.

9. Troubleshooting

Symptom Fix
Camera reports error when loading a photo No face / face too small / too dark → take a clear ID-style photo.
Standing in front of the camera does nothing Check: attendance enabled? person loaded on that camera? face large enough, no backlight, looking straight? Face model not ready → restart / update the camera software.
Wrong person recognised Raise Minimum similarity (e.g. 48–55) and replace both people's photos with clearer ones.
Must stand a long time Lower Minimum similarity slightly (≥ 38), improve the lighting, mount the camera lower.
Timesheet missing check-out The employee checked in only once — use Manual entry, or raise count again after to avoid repeated records when walking past.
Night shift split over 2 days Set Workday rollover after the night shift's end (e.g. shift ends 06:00 → set 08:00 if the day shift starts after 08:00).