All Query Commands in ZKTeco PUSH Protocol

Based on the Security PUSH Communication Protocol (Version 3.1.2, Doc Version 4.8), "Query" commands are primarily in Section 9.4 Query (pages 112-115), which allow the server to
request data from the device. The device responds by pushing results via HTTP POST to /iclock/querydata?SN=<SN>&type=<query_type>&cmdid=<ID>. Queries support filtering (filter), field
selection (fielddesc), and tables (e.g., user, biodata).
Query-like commands also include Count (Section 9.3, pages 110-111) for record counts and GET OPTIONS (Section 9.5, pages 116-120) for configuration retrieval. These are included below
as they function similarly (device pushes results to /iclock/querydata?type=options or similar).
All commands are sent in heartbeat responses (/iclock/service/control). Responses from device: ID=<CmdID>&Return=<value>&CMD=<TYPE> (Return ≥0 = success; see Appendix 1 for
errors).
1. Data Query Commands (C:99 / C:415: DATA QUERY)
These retrieve records from specified tables.

Comma Purpose Format Parameters Usage Example Response Handling Notes

nd ID

C:99 Query C:99:DATA QUERY - tablename: e.g., biodata, C:99:DATA QUERY Device POSTs to For bio types 0-10 (e.g., 1=FP,
biometric/unifi tablename=<table>,fieldd biophoto, templatev10. - fielddesc: tablename=biodata,fielddes /iclock/querydata with tab- 9=Visible Face, 10=Visible
ed data (e.g., esc=<fields>,filter=<cond * (all fields) or comma-separated c=*,filter=Type=9$ separated records (e.g., Pin=1$ Palm; V1.5+). Supports hybrid
templates, > list (e.g., Pin,Type,tmp). - filter: (HT)Pin=1 (HT)Type=9$ ID.
photos). Tab-separated conditions (e.g., (HT)tmp=<Base64>).
Type=9$(HT)Pin=1; $(HT)=\t).
Empty=*.

C:415 Query general C:415:DATA QUERY - tablename: e.g., user, holiday, C:415:DATA QUERY Device POSTs to General tables; supports elevator
data (e.g., tablename=<table>,fieldd [APList] (special for access tablename=user,fielddesc= /iclock/querydata with records privileges (V2.9+). For special
users, esc=<fields>,filter=<cond points). - fielddesc: * or list (e.g., *,filter=* (e.g., Pin=1$(HT)Name=John$ tables like [APList]: No filter.
holidays, > Pin,Name). - filter: e.g., Pin=1 or (HT)CardNo=123).
elevator *.
configs).
2. Count Query Commands (C:80 / C:288: DATA COUNT)
These retrieve the number of records matching criteria.

Command Purpose Format Parameters Usage Example Response Handling Notes

ID

C:80 Count biometric records C:80:DATA COUNT - <table>: e.g., biophoto, biodata. - C:80:DATA COUNT Device POSTs to /iclock/querydata For hybrid bio;
(e.g., templates/photos). <table> [Type=<n>] Type (optional): 0-10 (bio type, biophoto Type=9 with single line: e.g., count=5. omit Type for
e.g., 9=Visible Face). total. V1.5+.

C:288 Count general records C:288:DATA COUNT - <table>: e.g., user, identitycard. C:288:DATA COUNT Device POSTs to /iclock/querydata Basic tables; no
(e.g., users). <table> No Type param. user with: e.g., count=100. filters.

3. Options Query Commands (C:408 / C:409 / C:410: GET OPTIONS)

These query device configuration/parameters, grouped by category.

Comma Purpose Format Parameters Usage Example Response Handling Notes

nd ID
C:408 Get basic C:408:GET Comma-separated params C:408:GET OPTIONS Device POSTs to /iclock/querydata? Basic: SN, FW, counts
options (e.g., OPTIONS (e.g., ~SerialNumber,FirmVer,User type=options with: e.g., (users/FP/face).
device info, <param1>,<param2 ~SerialNumber,FirmVer,Use Count ~SerialNumber=123456789$
counts). >,... rCount). Prefix ~ for read- (HT)FirmVer=8.0.4.1$(HT)UserCount=7.
only (e.g., limits).
C:409 Get advanced C:409:GET e.g., C:409:GET OPTIONS POST to /iclock/querydata?type=options Advanced features (V2.9+):
options (e.g., OPTIONS IclockSvrFun,OverallAntiF IclockSvrFun,OverallAntiFun with values (e.g., IclockSvrFun=1$ ADMS, anti-passback, event
security, <param1>,<param2 unOn,AccSupportFunList. On (HT)OverallAntiFunOn=0). types. AccSupportFunList:
ADMS). >,... Bitmask (positions 0-62).
C:410 Get biometric C:410:GET e.g., C:410:GET OPTIONS POST to /iclock/querydata?type=options Bio support (V1.5+):
options (e.g., OPTIONS FingerFunOn,FaceFunOn,F FingerFunOn,FaceFunOn,FP with: e.g., FingerFunOn=1$ FP/Face/FV/PV; versions (e.g.,
algo versions). <param1>,<param2 PVersion,FaceVersion. Version (HT)FaceFunOn=1$(HT)FPVersion=10. FP=10).
>,...
Additional Notes
 Common Workflow: Send command in heartbeat response. Device processes and pushes results asynchronously (within 10-30s). Use cmdid in querydata URL to match (e.g.,
&cmdid=99).
 Filtering: Supports filter=* (all), equality (Pin=1), ranges (StartTime>=20240101), or bio-specific (Type=9$(HT)Valid=1).
 Errors: Device may return -1 (invalid table), -30 (invalid param; V3.8+). Server should retry on timeout.
 Tables Supported: Queries work with upload tables (e.g., user, biodata; see prior table details). For special: [APList] (access points), [DevProperty] (properties).
 Revisions: V4.8 adds video intercom queries (9.4); V1.5+ hybrid bio filters; V2.9+ elevator/expansion queries.
 PHP Integration: In ZKTecoPushHandler, parse /iclock/querydata endpoint similarly to data pushes, matching cmdid to queue response.
Examples of C:99 Bio Query Commands

The C:99:DATA QUERY command is used to query biometric data from the device, such as unified templates (biodata), fingerprint templates (templatev10), or comparison photos (biophoto). It
targets bio-specific tables and supports filtering by biometric type (0-10, per Appendix 18), user PIN, validity, etc. The device responds by pushing results to /iclock/querydata?
SN=<SN>&type=<table>&cmdid=99 in tab-separated format (e.g., Pin=1$(HT)Type=1$(HT)tmp=<Base64_template> for templates).

Below are practical examples for common biometric types. Each includes:

 Scenario: Use case.

 Command: Full syntax (sent in heartbeat response).
 Expected Response: Sample device push (simplified; actual includes all fields like no, index, valid, duress, majorver, minorver, format, tmp for templates).
 Notes: Tips and bio type details (from Sections 10.11, 7.11; V1.5+ for hybrid).

Scenario Command Expected Response (Device POST Body) Notes

Query all valid C:99:DATA QUERY Pin=123$(HT)no=0$(HT)index=0$(HT)valid=1$(HT)duress=0$(HT)type=1$ Filters valid FPs only; format=0
fingerprints for a tablename=biodata,fielddesc=*,filter (HT)majorver=10$(HT)minorver=0$(HT)format=0$ (ZK),1(ISO),2(ANSI). Use for
user (Type 1=FP) =Type=1$(HT)Pin=123$ (HT)tmp=ABC123Base64TemplateData (one line per finger; multiple lines for fingers enrollment sync.
(HT)Valid=1 0-9)
Query NIR face C:99:DATA QUERY Pin=456$(HT)type=2$(HT)tmp=DEF456Base64FaceTemplate Pin=789$(HT)type=2$ No PIN filter (all users); fielddesc
templates for all tablename=biodata,fielddesc=Pin,typ (HT)tmp=GHI789Base64FaceTemplate limits output. For face devices like
users (Type 2=NIR e,tmp,filter=* SpeedFace.
Face)
Query finger-vein C:99:DATA QUERY Pin=111$(HT)no=1$(HT)index=5$(HT)valid=1$(HT)duress=0$(HT)type=3$ no=1 (right index finger); duress=0
templates by finger tablename=biodata,fielddesc=*,filter (HT)majorver=5$(HT)minorver=0$(HT)tmp=JKL111Base64VeinData (normal, not duress). Vein models
index (Type =Type=3$(HT)no=1$(HT)duress=0 only.
3=Finger-Vein)
Query visible light C:99:DATA QUERY Pin=222$(HT)no=0$(HT)index=0$(HT)valid=1$(HT)duress=0$(HT)type=10$ V4.8+ for Type 10; for palm
palm templates tablename=biodata,fielddesc=*,filter (HT)majorver=1$(HT)minorver=0$(HT)tmp=MNO222Base64PalmTemplate vein/visible devices. No multi-instance
(Type 9=Visible =Type=10$(HT)Pin=222 (no=0).
Light Face or
10=Visible Light
Palm; use 10)
Query comparison C:99:DATA QUERY Pin=333$(HT)filename=333_face.jpg$(HT)type=2$(HT)size=95040$ Photos in JPG Base64; Type=2 (NIR
photos for a specific tablename=biophoto,fielddesc=*,filte (HT)content=Base64JPGPhotoData Face). For verification photo retrieval.
bio type (Use r=Type=2$(HT)Pin=333
biophoto table)
Query all duress C:99:DATA QUERY size=512$(HT)uid=1$(HT)pin=444$(HT)fingerid=16$(HT)valid=3$ Legacy templatev10 table (v10 algo);
 fingerprints (Type tablename=templatev10,fielddesc=*, (HT)template=Base64FPTemplate$(HT)reserved=0$(HT)endtag (valid=3=duress) fingerid +16 for duress (e.g., 16=left
1=FP, duress=1) filter=Pin=444$(HT)valid=3 thumb duress).
Query unified First: C:80:DATA COUNT biodata Count response: count=4 Query: Pin=555$(HT)... (4 lines) Use C:80 first for efficiency; filter=*
templates count Type=1 Then (if count>0): for all fields.
indirectly (Combine C:99:DATA QUERY
with C:80 for count, tablename=biodata,fielddesc=Pin,filt
then query) er=Type=1

Additional Usage Tips

 Filter Syntax: $(HT) = tab separator. Supports AND (spaces), OR (via multiple queries), ranges (e.g., index>=0$(HT)index<=9), equality (Valid=1).
 Field Selection: * = all (e.g., for biodata: Pin, no, index, valid, duress, type, majorver, minorver, format, tmp). Limit for smaller payloads.
 Error Handling: If invalid (e.g., unsupported Type), device returns ID=99&Return=-30&CMD=DATA QUERY (-30=invalid param).
 Hybrid Support: For multi-bio (e.g., face+FP), query by Type or combine filters (V3.1+).
 PHP Handling: In your handler, parse /iclock/querydata body, match cmdid=99, store/decode Base64 tmp (e.g., via base64_decode).

These examples are derived directly from protocol specs (Sections 9.4, 10.7-10.11). For more, query specific tables like ATTPHOTO for attendance snaps.
C:395 Enrollment Commands: Remote Registration Protocol

The C:395 command is used for remote enrollment/registration of users or biometrics on the device, initiated by the server (your application). It's detailed in Section 9.6 Remote Registration
(pages 127-130 of the document). This allows the server to trigger enrollment sessions on the device without physical interaction, useful for centralized management (e.g., via mobile app or
admin panel).

The command has two main subtypes: ENROLL_INFO (for general/non-bio data like cards) and ENROLL_BIO (for biometrics like fingerprints or faces). Both use the same CmdID=395 but
differ in parameters and response handling. The device prompts the user for input (e.g., "Place finger"), collects data, and pushes results back to the server via specific tables (e.g., EnrollInfoData
or BioData).

Key Characteristics

 Trigger: Sent in heartbeat response (/iclock/service/control).

 Process: Device enters enrollment mode for RETRY attempts. Success: Saves data (if MODE=1) and pushes to server. Failure: Returns error (e.g., -1=no data).
 Response: ID=395&Return=<value>&CMD=ENROLL_<TYPE> (Return=0=success; see Appendix 1 for errors, e.g., -30=invalid param).
 Device Push: Asynchronous POST to /iclock/cdata?SN=<SN>&table=<table> with collected data (tab-separated).
 Security: Optional encryption (Ch. 2); supports overwrite for existing users.
 Revisions: V4.6+ modifies remote reg protocol; V4.8+ adds BIOPHOTO optional field for ENROLL_BIO.
 Limitations: Device must support the TYPE (check via AccSupportFunList in registration); max retries ~3-5.

Command Subtypes and Details

Below is a table with subtypes, formats, parameters, examples, and notes.

Purp Parame Usage

Subtype Format Expected Device Response/Push Notes
ose ters Example
 - TYPE:
Enrollm
ent type
(0=MF
card,
11=QR
code,
12=Heal
th QR;
Enroll see
gener Appendi
al x 3 for
For cards:
data verify
Device
(e.g., modes). C:395:ENR
reads card,
MF - PIN: OLL_INFO
C:395:ENRO encodes in
cards, User ID TYPE=0
LL_INFO TMP. V2.3+
passw (int/strin PIN=1
ENROL TYPE=<n> - Response: ID=395&Return=0&CMD=ENROLL_INFO (success). - Push: POST to /iclock/cdata? for QR
ords, g, e.g., RETRY=3
L_INFO PIN=<id> table=EnrollInfoData with Pin=1$(HT)TMP=<Base64_card_data>$(HT)CardNo=<hex>. If fail: Return=-1. (TYPE=11/
or 1; auto- MODE=1
RETRY=<n> 12; decrypt
non- assign if (Enroll MF
MODE=<0/1> with
bio 0). - card for user
QRCodeDec
like RETRY 1)
ryptKey).
QR/h :
No bio.
ealth Attempt
codes s (1-10;
). default
3). -
MODE:
0=Don't
save/upl
oad,
1=Save
and
upload
results.
ENROL Enroll C:395:ENRO - TYPE: C:395:ENR - Response: ID=395&Return=0&CMD=ENROLL_BIO. - Push: POST to /iclock/cdata?table=BioData with Multi-
L_BIO biome LL_BIO Bio type OLL_BIO Pin=1$(HT)no=0$(HT)index=0$(HT)valid=1$(HT)duress=0$(HT)type=1$(HT)majorver=10$ finger: Send
tric TYPE=<0- (0=Gene TYPE=1 (HT)minorver=0$(HT)format=0$(HT)tmp=<Base64_template>$(HT)BIOPHOTO=<Base64_photo>. Multi: multiple
templ 10> NO=<0- ral, NO=0 LF-separated lines. commands
ates 9> PIN=<id> 1=FP, PIN=1 or use
(e.g., RETRY=<n> 2=NIR RETRY=3 NO=0-9.
FP, OVERWRITE Face, OVERWRIT For duress:
face, =<0/1> 3=Finge E=1 Set
palm) MODE=<0/1> r-Vein, MODE=1 duress=1 in
. [BIOPHOTO 4=Palm- (Enroll left push.
Supp =<Base64>] Vein, thumb FP for Hybrid:
orts 5=Visibl user 1) Type=9/10
multi- e Palm, for visible
templ 6=Iris, light
ates. 7=RFID (V3.1+).
, 8=QR,
9=Visibl
e Face,
10=Visi
ble
Palm;
Appendi
x 18). -
NO:
Instance
(0-9 for
fingers/e
yes; 0
for
face/pal
m). -
PIN:
User ID
(0=auto)
.-
RETRY
:
Attempt
s (1-10).
 -
OVER
WRITE:
0=Don't
overwrit
e
existing,
1=Over
write. -
MODE:
0=No
save/upl
oad,
1=Save
and
upload.
-
BIOPH
OTO
(optiona
l,
V4.8+):
Base64
photo
for bio
(e.g.,
face
capture
during
enroll).

Multi-Template Enrollment Example (Batch Fingers)

For enrolling multiple fingers (e.g., 2 thumbs), send separate commands or chain in one response:
text
C:395:ENROLL_BIO TYPE=1 NO=0 PIN=1 RETRY=3 OVERWRITE=1 MODE=1
C:395:ENROLL_BIO TYPE=1 NO=1 PIN=1 RETRY=3 OVERWRITE=1 MODE=1

 Device pushes each to BioData sequentially.

 Total: Up to 10 fingers (NO=0-9); device queues if busy.

Workflow (Step-by-Step)

1. Server Sends Command: In heartbeat response.

2. Device Enters Mode: Displays prompt (e.g., "Place Finger on Reader"), retries up to RETRY times.
3. User Interaction: User provides input (e.g., scans finger/card).
4. Success/Fail: If MODE=1 and success, saves locally and pushes data. Server receives via table handler (e.g., processBioData() in PHP class).
5. Server Processes: Validate push (e.g., decode Base64 tmp), update DB, optional: Send C:295:DATA UPDATE user to sync privileges.

Error Codes (Common for C:395)

 0: Success.
 -1: No data collected (timeout/user cancel).
 -2: Invalid TYPE/NO (unsupported bio).
 -30: Invalid param (e.g., PIN=0 on non-auto device; V3.8+).
 -18: No space (full templates).