Events API

  1. Home
  2. Docs
  3. Modis Lock User’s Manual
  4. API
  5. Events API

Events API

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_timeend_timeevent_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:
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:
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:
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 (pinrfidotptotpu2f)
  • 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:
GET /api/v1.0/key/(int: user_id)
GET KEY stuff

GET /api/v1.0/key/(int: user_id)?protocol=(string: protocol_type)
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:
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:
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 (pinrfidotptotpu2f)
  • 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:
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:
Was this article helpful to you? Yes No

How can we help?