Events API exposes over REST API the ability for custom applications to access the eventson the host. These events are things like accesses and denials. In each event several pieces of information are attached. Each event contains a user, a location, time, and direction. An easy use of the event API is in cases of a check-in / check-out application that would notify people of who is in the building. Another use might be for a time clock application that would be easily integrated into a payroll system.
GET
/api/v1.0/event/
(int: user_id)- Retrieve access events from logs
GET
/api/v1.0/event/
(int: user_id)?
(datetime: start_time)&
(datetime: end_time)&
(string: event_type)- Example Missing Parameter Request
GET /api/v1.0/event/0?start_time=2017-05-06 12:00:00&event_type=A Host: modislock.local Accept: application/json, text/javascript
Example Response
HTTP/1.1 200 OK Vary: Accept Content-type: text/javascript { "message": { "end_time": "A valid end time is required: ex 2017-05-25 12:12:00" } }
Example Successful Request
GET /api/v1.0/event/12?start_time=2017-05-06 12:00:00&end_time=2017-08-08 12:00:00&event_type=A Host: modislock.local Accept: application/json, text/javascript
Example Response
HTTP/1.1 200 OK Vary: Accept Content-Type: text/javascript { "message": { "user": 12, "events": [ { "event_type": "ACCESS", "location_name": "READER 1", "id_event": 8450, "event_time": "2017-07-11 00:06:45", "user_id": 12, "location_direction": "ENTRY" }, { "event_type": "ACCESS", "location_name": "READER 3", "id_event": 14485, "event_time": "2017-07-18 18:13:30", "user_id": 12, "location_direction": "ENTRY" }, { "event_type": "ACCESS", "location_name": "READER 4", "id_event": 14794, "event_time": "2017-05-25 20:39:06", "user_id": 12, "location_direction": "EXIT" } ], "count": 3 } }
Parameters: - user_id (int) – Users ID number
- start_time (datetime) – Start of date and time to search
- end_time (datatime) – End of date and time where to search
- event_type (str) – Type of events to search
Warning
When a field is not provided (start_time, end_time, event_type), a help message will be returned
Note
To query a specific user, their user_id number is required.
Note
To query for all records of all users, user id should be 0.
Note
Accepted Event types are:
- A Access Events
- B Both Access and Denied
- D Denied Events
Query Parameters: - sort –
event_time
- limit – No limit
Request Headers: - Authorization – X-APP-ID / X-APP-PASSWORD or X-APP-TOKEN (Password or Token generated by administration)
Status Codes: - 200 OK – No errors have occurred
- 403 Forbidden – Credentials missing for api usage
GET
/api/v1.0/user
-
GET
/api/v1.0/user/
- Directory of all system users
Example Request
GET /api/v1.0/user/ HTTP/1.1 Host: modislock.local Accept: application/json, text/javascript
Example Response
HTTP/1.1 200 OK Vary: Accept Content-Type: text/javascript { "message": { "count": 489 }, "user": [ { "last_active": "2017-07-18 05:31:58", "last_name": "Bob", "email": "jbob@modislab.com", "id": 3, "is_admin": true, "first_name": "Jim" }, { "last_active": "2017-07-25 06:48:45", "last_name": "Happy", "email": "shappy@modislab.com", "id": 4, "is_admin": false, "first_name": "Steven" }, ... ] }
count in the message refer to the number of user records in the returning querylast_active represents with the last validation or denial has occurred is_admin user has access to the enrollment administration application
Request Headers: - Authorization – X-APP-ID / X-APP-PASSWORD or X-APP-TOKEN (Password or Token generated by administration)
Status Codes: - 200 OK – No errors have occurred
- 403 Forbidden – Credentials missing for api usage
POST
/api/v1.0/user
- Add user to system
POST
/api/v1.0/user
- Example Request
POST /api/v1.0/user Host: modislock.local Accept: application/json, text/javascript
Example Response
HTTP/1.1 200 OK Vary: Accept Content-Type: text/javascript { "message": { "success": "New user id 505 added" }, "user": { "email": "mrogers@modislab.com", "is_admin": false, "id": 505, "last_name": "Rogers", "first_name": "Mary" } }
Form Parameters: - first_name – The first name of the new user
- last_name – The last name of the new user
- email – Email of the user. Must be unique on the system
- is_admin – true/false if the user is going to have admin privileges
- password – if is_admin is set to true a password is required, otherwise optional
Request Headers: - Authorization – X-APP-ID / X-APP-PASSWORD or X-APP-TOKEN (Password or Token generated by administration)
- Content-Type – application/x-www-form-urlencoded
Status Codes: - 201 Created – No errors have occurred and record was created
- 400 Bad Request – If the user already exists or required field needed
- 403 Forbidden – Credentials missing for api usage
PUT
/api/v1.0/key/
(int: user_id)- API to update the status of a given user and key
PUT
/api/v1.0/key/
(int: user_id)
Example Request
PUT /api/v1.0/key/5 Host: modislock.local Accept: application/json, text/javascript
Example Response
HTTP/1.1 201 OK Vary: Accept Content-Type: text/javascript { "message": { "success": "Updated key for id 2 is now Enabled", "key": { "enabled": true, "created_on": "2017-10-10 14:30:43", "user_id": 2, "key": 2492 } } }
Parameters: - user_id – User ID number
Form Parameters: - protocol – The protocol that will be enrolled (pin, rfid, otp, totp, u2f)
- enable – true / false
Request Headers: - Authorization – X-APP-ID / X-APP-PASSWORD or X-APP-TOKEN (Password or Token generated by administration)
- Content-Type – application/x-www-form-urlencoded
Status Codes: - 201 Created – No errors have occurred and record was updated
- 403 Forbidden – Credentials missing for api usage
GET
/api/v1.0/key/
(int: user_id)- GET KEY stuff
GET
/api/v1.0/key/
(int: user_id)?protocol=
(string: protocol_type)- A user_id and protocol is required.
- The protocol types available are:
- pin Simple PIN code rfid RFID code otp OTP code u2f U2F code rules User access rules count Count of types of keys available to the user
Example Request
GET /api/v1.0/key/1?protocol=pin HTTP/1.1 Host: modislock.local Accept: application/json, text/javascript
Example Response
HTTP/1.1 200 OK Vary: Accept Content-Type: text/javascript { "message": { "key": { "user_id": 1, "enabled": true, "created_on": "2017-10-10 13:15:05", "key": 4444 }, "protocol": "pin" } }
Request Headers: - Authorization – X-APP-ID / X-APP-PASSWORD or X-APP-TOKEN (Password or Token generated by administration)
Status Codes: - 200 OK – No errors have occurred
- 403 Forbidden – Credentials missing for api usage
DELETE
/api/v1.0/key/
(int: user_id)- Deletes a users key
DELETE
/api/v1.0/key/
(int: user_id)?protocol=
(string: protocol_type)- Example Request
DELETE /api/v1.0/key/301?protocol=pin Host: modislock.local Accept: application/json, text/javascript
Example Response
HTTP/1.1 204 OK Vary: Accept Content-Type: text/javascript
Parameters: - user_id – User ID number
Request Headers: - Authorization – X-APP-ID / X-APP-PASSWORD or X-APP-TOKEN (Password or Token generated by administration)
Status Codes: - 204 No Content – No errors have occurred and record was created
- 403 Forbidden – Credentials missing for api usage
POST
/api/v1.0/key/
(int: user_id)- API that adds a key to given user
POST
/api/v1.0/key/
(int: user_id)- Example Request
POST /api/v1.0/key/5 Host: modislock.local Accept: application/json, text/javascript
Example Response
HTTP/1.1 200 OK Vary: Accept Content-Type: text/javascript { "message": { "success": "pin key added for user id 5", "key": { "created_on": "2017-11-02 14:07:44", "user_id": 5, "key": 7774, "enabled": true } } }
Parameters: - user_id – User ID number
Form Parameters: - protocol – The protocol that will be enrolled (pin, rfid, otp, totp, u2f)
- key – If protocol dictates, a identification PIN code. This can also be generated from an API call to:
- key2 – If protocol dictates, a second key. An example would be OTP which requires the AES code if the OTP key is to be locally validated.
Request Headers: - Authorization – X-APP-ID / X-APP-PASSWORD or X-APP-TOKEN (Password or Token generated by administration)
- Content-Type – application/x-www-form-urlencoded
Status Codes: - 201 Created – No errors have occurred and record was created
- 403 Forbidden – Credentials missing for api usage
GET
/api/v1.0/utils
- Various system utilities
GET
/api/v1.0/utils?feature=
(string: requested_feature)
- Valid features are:
- key_gen A unique PIN code used in multiple protocols. This PIN is guaranteed to be unique. totp_gen A unique challenge generated for TOTP enrollments sys_tempCurrent system temperature reader_status Not yet implemented door_sensors Not yet implemented
Example TOTP
GET /api/v1.0/utils?feature=totp_gen HTTP/1.1 Host: modislock.local Accept: application/json, text/javascript
Example Response
HTTP/1.1 200 OK Vary: Accept Content-Type: text/javascript { "message": { "totp_code": "7YVYAQQ3UQMJXXOJ" } }
Example Reader Status
GET /api/v1.0/utils?feature=reader_status HTTP/1.1 Host: modislock.local Accept: application/json, text/javascript
Example Response
HTTP/1.1 200 OK Vary: Accept Content-Type: text/javascript { "message": { "1": "DISCONNECTED", "2": "DISCONNECTED", "3": "DISCONNECTED", "4": "DISCONNECTED" } }
Example Door Status
GET /api/v1.0/utils?feature=door_status HTTP/1.1 Host: modislock.local Accept: application/json, text/javascript
Example Response
HTTP/1.1 200 OK Vary: Accept Content-Type: text/javascript { "message": { "1": "INACTIVE", "2": "INACTIVE" } }
Request Headers: - Authorization – X-APP-ID / X-APP-PASSWORD or X-APP-TOKEN (Password or Token generated by administration)
Status Codes: - 200 OK – No errors have occurred
- 403 Forbidden – Credentials missing for api usage