Hikvision ISAPI Access Control API: 14 Calls, Exact Bodies
The 14 Hikvision ISAPI access-control endpoints our MIT TypeScript client calls, with the exact request bodies it sends and the response fields it reads.
Everything our open-source TypeScript client does with a Hikvision access-control terminal goes through 14 ISAPI endpoints, plus one picture download from a URL the device hands back. One endpoint identifies the device, four manage users, five handle faces, three configure event push and one reads the event log.
Each call below comes with the request body exactly as the library sent it and the fields the client reads from the answer. We captured the bodies on 2026-11-16 by pointing hikvision-isapi-ts at a local fake device, running every method except the picture download, and recording what arrived.
This isn't Hikvision's documentation. It covers the access-control subset one client calls. The one terminal this page names is a DS-K1T343MX on firmware V4.39.80, and we make no claim that any other model or firmware does the same. Several calls have traps that our earlier article and the library's README cover in depth, so each gets only a short note here.
The 14 endpoints at a glance
Apart from that picture download, every request our client makes goes to one of the 14 method and path pairs below, written the way it sends them. In the paths, <id> is the ID of a push target and <employeeNo> is the user's employee number. Every face call names the same face library: FDID=1 with faceLibType=blackFD.
| Method | Path | What it does |
|---|---|---|
| GET | /ISAPI/System/deviceInfo |
Reads the device name, model, MAC address and firmware version |
| POST | /ISAPI/AccessControl/AcsEvent?format=json |
Pages through the event log |
| POST | /ISAPI/AccessControl/UserInfo/Search?format=json |
Pages through the users stored on the device |
| POST | /ISAPI/AccessControl/UserInfo/Record?format=json |
Creates a user |
| PUT | /ISAPI/AccessControl/UserInfo/Modify?format=json |
Updates a user, with the same body as Record |
| PUT | /ISAPI/AccessControl/UserInfo/Delete?format=json |
Deletes a user |
| POST | /ISAPI/Intelligent/FDLib/FaceDataRecord?format=json |
Uploads the first face picture for a user |
| PUT | /ISAPI/Intelligent/FDLib/FDModify?format=json&FDID=1&faceLibType=blackFD&FPID=<employeeNo> |
Replaces an existing face picture |
| PUT | /ISAPI/Intelligent/FDLib/FDSearch/Delete?format=json&FDID=1&faceLibType=blackFD |
Deletes a face |
| PUT | /ISAPI/Intelligent/FDLib/FDDelete?format=json&FDID=1&faceLibType=blackFD |
Deletes a face on the legacy path, after the device rejects the one above |
| POST | /ISAPI/Intelligent/FDLib/FDSearch?format=json |
Pages through face records, optionally for one user |
| GET | /ISAPI/Event/notification/httpHosts |
Reads the push configuration as XML |
| PUT | /ISAPI/Event/notification/httpHosts/<id> |
Writes one push target as XML |
| POST | /ISAPI/Event/notification/httpHosts/<id>/test |
Asks the device to self-test that push target |
The picture download isn't listed because its URL comes from FDSearch's answer.
Digest auth, HTTPS and format=json
Every request goes through HTTP Digest authentication, MD5 with qop=auth, per RFC 7616. Each call opens with an unauthenticated request that collects a fresh nonce. If the signed request after it still gets a 401, the client repeats the whole exchange exactly once, for the stale-nonce reason the README's traps section explains. Both requests in an exchange carry the body, so a face upload sends its JPEG twice, or four times when that retry runs.
The client defaults to HTTPS, and https: false switches it to plain HTTP. Under Bun it passes tls: { rejectUnauthorized: false } on every request, which turns certificate verification off so a self-signed device certificate gets through. Under Node, hand it a fetch bound to an undici Agent with connect: { rejectUnauthorized: false }, or set https: false.
All paths except deviceInfo and the httpHosts calls carry ?format=json. JSON bodies go out with Content-Type: application/json and the two face uploads as multipart/form-data.
What does statusCode 1 mean?
In our client it means success; a comment in its status.ts says "statusCode 1 means OK". The client reads statusCode, statusString and subStatusCode from the JSON answer to each user and face write (UserInfo Record, Modify and Delete, FaceDataRecord, FDModify and the face delete). A write counts as done when the HTTP status is OK and statusCode is 1.
An HTTP-OK answer with an empty or non-JSON body also counts as success. A code comment gives the reason: "some firmwares answer empty 200". Any other answer throws an IsapiError with op, status and httpStatus. Its message is shaped like <op>: HTTP <httpStatus> <statusString>, with unknown in place of an empty statusString and (<subStatusCode>) appended when there is one. Missing fields parse to statusCode -1 and empty strings.
Reads and setHttpHost throw a plain Error on a non-OK HTTP status instead, and setHttpHost never checks statusCode in the device's answer.
The production adapter in ShipKit Access, where this client came from, matches subStatusCode as lower-cased substrings. A code containing alreadyexist or existed, and neither notexist nor noexist, reads as "already exists". The adapter matches that one loosely, and its comment says why: "neighbouring firmwares spell the same condition differently". Picture rejections, with substrings such as nofacedetected, lowfacepicquality and picsizeexceedlimit, count as permanent, since retrying the same photo won't help. Those are strings our code matches, not a list of codes we've seen a terminal return.
How do ISAPI searches page?
AcsEvent, UserInfo/Search and FDSearch return results in pages, and our client walks all of them the same way. Every page asks for maxResults 30, and the first starts at searchResultPosition 0. AcsEvent and UserInfo/Search also carry a searchID, a UUID the client creates once and repeats on every page of that scan. FDSearch sends none.
After each page the client reads responseStatusStrg and numOfMatches. It asks for another page only while responseStatusStrg is exactly MORE, moving searchResultPosition forward by the numOfMatches the device reported. If the device reports MORE with numOfMatches at 0 or missing, the scan stops anyway; our earlier article explains that guard.
Get device info: GET /ISAPI/System/deviceInfo
Our client sends a plain GET with no body and reads the answer as XML. It pulls the <deviceName>, <model>, <macAddress> and <firmwareVersion> tags out by name and returns them as { deviceName, model, macAddress, firmwareVersion }. Compare model and firmwareVersion with the DS-K1T343MX on V4.39.80 before you rely on a note below that names that terminal.
Add or update a user: UserInfo Record and Modify
Our client creates a user with POST /ISAPI/AccessControl/UserInfo/Record?format=json and updates one with PUT /ISAPI/AccessControl/UserInfo/Modify?format=json, sending the same body to both. In this and every later example, the employee number 1001, the person's name, the dates, and the push target's address, port, path, slot ID, user name and password are values we picked. Keys, nesting, types and fixed values are the library's own, and the JSON goes out without the indentation.
{
"UserInfo": {
"employeeNo": "1001",
"name": "Example Person",
"userType": "normal",
"Valid": {
"enable": true,
"beginTime": "2026-01-01T00:00:00",
"endTime": "2037-12-31T23:59:59",
"timeType": "local"
},
"doorRight": "1",
"RightPlan": [
{
"doorNo": 1,
"planTemplateNo": "1"
}
]
}
}
Mind the types: doorRight and planTemplateNo are strings, doorNo is a number and enable is a boolean. The library always writes userType normal, door 1 and plan template 1. Valid takes device-local times in YYYY-MM-DDThh:mm:ss form with timeType local and no offset, unlike the AcsEvent window, which carries one. Our production adapter defaults the validity window to 2020-01-01T00:00:00 through 2037-12-31T23:59:59. The comment on those defaults records that the DS-K1T343MX rejects years past 2037.
To save a user whether or not they already exist on the device, the production adapter calls Modify first and falls back to Record when the device rejects it. Any device-answered rejection triggers that fallback. As its comment puts it, "The firmware's 'no such person' status codes are unconfirmed". A transport failure propagates instead.
Delete and list users: UserInfo Delete and Search
Deleting a user also goes out as a PUT, to /ISAPI/AccessControl/UserInfo/Delete?format=json, with the employee number inside a condition object. A comment on that call in our client says it removes the person together with their enrolled face and credentials. This is the body it sent:
{
"UserInfoDelCond": {
"EmployeeNoList": [
{
"employeeNo": "1001"
}
]
}
}
The user search carries a condition that holds nothing but the paging fields:
{
"UserInfoSearchCond": {
"searchID": "7d42f1e7-be48-4e99-b131-b986cfc87189",
"searchResultPosition": 0,
"maxResults": 30
}
}
From each page the client reads responseStatusStrg, numOfMatches and the UserInfo array under UserInfoSearch. Its type for each user has employeeNo, name and userType, with Valid (beginTime, endTime) marked optional.
Upload a face picture: FaceDataRecord and FDModify
A face goes to the device as multipart/form-data in two parts, the JSON part first and the raw JPEG second. A comment in our multipart builder calls that order a firmware requirement. The same comment explains why FPID carries the user's employeeNo: "that is how the terminal links the face to the person record". Here are the two parts of POST /ISAPI/Intelligent/FDLib/FaceDataRecord?format=json as the client sent them, with <boundary> and <JPEG bytes> standing in for the real values:
--<boundary>
Content-Disposition: form-data; name="FaceDataRecord"
Content-Type: application/json
{"faceLibType":"blackFD","FDID":"1","FPID":"1001","name":"Example Person"}
--<boundary>
Content-Disposition: form-data; name="img"; filename="face.jpg"
Content-Type: image/jpeg
<JPEG bytes>
--<boundary>--
The body uses CRLF line breaks, and the request's Content-Type header is multipart/form-data; boundary=<boundary>. Replacing a picture uses PUT /ISAPI/Intelligent/FDLib/FDModify?format=json&FDID=1&faceLibType=blackFD&FPID=1001 with the same two parts. Only the JSON part's name changes, to FaceDataModify, and FPID rides in the query string as well as in the JSON.
Our client's notes say FaceDataRecord only creates and that an upload for an FPID that already has a face gets HTTP 400 deviceUserAlreadyExistFace; that's why a new photo for an enrolled user goes through FDModify (see the README traps).
Search, download and delete faces
FDSearch pages through the face library, and its body breaks the pattern of the other two searches. It puts the paging fields and the face library identifiers at the top level and leaves out both searchID and the wrapper object. FPID is optional and narrows the search to one user; our capture included it:
{
"searchResultPosition": 0,
"maxResults": 30,
"faceLibType": "blackFD",
"FDID": "1",
"FPID": "1001"
}
From the answer the client reads responseStatusStrg, numOfMatches and a MatchList array whose entries carry FPID and faceURL. A comment in the client says some firmwares wrap those fields in an FDSearchResult object and that "there is no live device to confirm which shape ours uses", so our code accepts either shape. We haven't confirmed either shape on a real terminal.
The client downloads a picture with a GET to its faceURL, using the same digest auth, and gets the JPEG bytes back.
To delete a face, the client sends PUT /ISAPI/Intelligent/FDLib/FDSearch/Delete?format=json&FDID=1&faceLibType=blackFD with the FPID in a list of value objects:
{
"FPID": [
{
"value": "1001"
}
]
}
When the device rejects that call, the same body goes to the legacy PUT /ISAPI/Intelligent/FDLib/FDDelete?format=json&FDID=1&faceLibType=blackFD, because which path a firmware answers varies and there's no capability probe (README traps).
Configure event push: httpHosts
Our client writes XML in one place, the push configuration. GET /ISAPI/Event/notification/httpHosts reads the current configuration, which the library returns as an XML string, and PUT /ISAPI/Event/notification/httpHosts/<id> writes one target, with the ID in the path and again in <id>. The XML goes out on a single line, so the breaks below are ours:
<HttpHostNotification version="2.0" xmlns="http://www.isapi.org/ver20/XMLSchema">
<id>1</id>
<url>/hik/event</url>
<protocolType>HTTP</protocolType>
<parameterFormatType>JSON</parameterFormatType>
<addressingFormatType>ipaddress</addressingFormatType>
<ipAddress>192.168.1.10</ipAddress>
<portNo>8099</portNo>
<httpAuthenticationMethod>none</httpAuthenticationMethod>
</HttpHostNotification>
With a user set, these three replace the none element:
<httpAuthenticationMethod>basic</httpAuthenticationMethod>
<userName>turnstile</userName>
<password>example</password>
An ingest password containing & once produced malformed XML and a bare HTTP 400, as a comment in the client records. So the library XML-escapes each string it interpolates.
In <url> our client writes only the path, whatever you pass, because per its notes, with ipaddress addressing, the device builds the target from <ipAddress>:<portNo> plus <url>. And on a DS-K1T343MX running V4.39.80, rewriting a full URL there to the bare path got the terminal connecting within seconds (the full story).
The self-test, a POST to httpHosts/<id>/test, goes out with no body; our client maps HTTP 400, 405 and 501 to "unsupported", success to "ok" and anything else to "failed". We chose that mapping because a DS-K1T343MX on V4.39.80 answered the self-test with HTTP 400, or with methodNotAllowed when the host definition was in the body (README traps).
Get access control events: AcsEvent
POST /ISAPI/AccessControl/AcsEvent?format=json reads the event log, and it's the only search here with a time window. startTime and endTime go out only when the caller passes them, as ISO timestamps with an explicit offset in the device's local wall-clock time, and they narrow the scan on the device. The client sends major 0 and minor 0. Our capture had both window fields set:
{
"AcsEventCond": {
"searchID": "d4792df7-e1d7-434b-b5e5-9fea2056174c",
"searchResultPosition": 0,
"maxResults": 30,
"major": 0,
"minor": 0,
"startTime": "2026-11-16T00:00:00+05:00",
"endTime": "2026-11-16T23:59:59+05:00"
}
}
Under AcsEvent the client reads responseStatusStrg, numOfMatches and the InfoList array. Its type for each event has major, minor, time and serialNo, with employeeNoString, name, cardReaderNo and currentVerifyMode marked optional.
The client doesn't filter by event type, so our example receiver keeps only major 5 with an employee number. A DS-K1T343MX on V4.39.80 answered beginSerialNo with HTTP 400 badJsonContent, so the client leaves it out and pages from the start, keeping events whose serialNo is above the one you pass in (why).
What our parser reads from a push
Our parser, parseNotification, accepts a push body in three shapes: multipart with the JSON in one part, an XML EventNotificationAlert, or plain JSON. A body with no AccessControllerEvent object counts as a heartbeat, and the example receiver answers every body posted to /hik/event with 200 OK. The parser's tests run on synthetic bodies. None of them was captured from a terminal.
For an access pass the parser wants eventType AccessControllerEvent, an AccessControllerEvent.majorEventType of 5, a non-empty employeeNoString, a numeric serialNo and a time, taken from the top-level dateTime or else AccessControllerEvent.time. It maps subEventType to minor and also reads name, currentVerifyMode and the top-level ipAddress and macAddress. Our earlier article shows the parser code.
Our MIT-licensed client, hikvision-isapi-ts, implements every call on this page. Install it with bun add github:Dave93/hikvision-isapi-ts; the package lives on GitHub only. Our team extracted it from ShipKit Access, a $249 one-time licence with full source.