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_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
        }
    }
}

Form Parameters:
Parameters:	user_id – User ID number
	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

Request Headers:
Parameters:	user_id – User ID number
	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
        }
    }
}

Form Parameters:
Parameters:	user_id – User ID number
	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

Modis Lock User's Manual

How can we help?