CloudAccess API Reference

The Lockt CloudAccess Cloud API is designed to provide customers with CloudAccess the ability to easily integrate with external systems. This reference is for Lockt CloudAccess only. For the SecureAccess API Reference, please click below:


CloudAPI For SecureAccess
This API is intended to be a simple, but powerful way for your organization to access common features of Lockt CloudAccess from any REST compatible client. New functions and endpoints will be added frequently. Please refer to the documentation below for reference.
Release 1.1.0
July 2022 Release - Enhancements, bug fixes, documentation updates

Release Details
Correction of bugs in relay calls. 
Expanded validation of user supplied values across all endpoints.
Addition of endpoints: /about, /maintenance, /location, /locationtype, /object, /user?missingcreds, /user?installers, /user?privileged
History of changes made to the API, feature adds, fixes, and other notes.


Changes


Endpoint Method Description Date
ALL ALL July release 1.1.0 baseline. 2022-07-01
/about GET Displays current release notes. 2022-07-10
/cedentialsummary GET List summary of credentials claimed and unclaimed. 2022-07-10
/doorstate GET List door battery levels. 2022-07-10
/location GET Get list of locations. 2022-07-10
/location POST Create locations. 2022-07-10
/object?listtypes GET Displays available object types. 2022-07-10
/object?type GET Displays object information using the provided object type. 2022-07-10
/acesslevel DELETE Delete access level. 2022-07-15
/credential?id GET Retreive credential by id. 2022-07-15
/credential?card_num GET Retreive credential by card_num. 2022-07-15
/ping GET Simple ping response to check connectivity and authorization. 2022-08-12
/settings GET Retrieve api settings. 2022-08-12
/site GET Retrieve basic site information. 2022-08-12
/user PUT Update user objects using only specified object properties. 2022-08-12
/user POST Bug fix for user update and delete requests. 2022-08-18
/fob PUT Reassign credentials tagged as FOBs to a different user, and update expiration date.. 2022-08-18
/doors?user_id GET Retrieves list of doors based on user_id. 2022-08-31
/user POST Performance improvements for single record operations. Reduces time needed to execute changes on single records. 2022-09-06
/doors?id_num GET Retrieves list of doors based on user id_num. 2022-09-08
/delegate GET Retrieves list of access levels tagged as delegate roles. 2022-09-08
/delegate?purge POST Purges expired delegate access levels. 2022-09-08
/delegate POST Creates delegate access level based on supplied door_id and assigns to supplied user_id. 2022-09-08
/credential GET Addition of access_expires and access_effective to all credential GET endpoints. 2022-11-11
/credential PUT New endpoint for direct management of credential data. 2022-11-11
/unlock POST New endpoint to provide momentary unlock capability for hard-wired doors. 2022-11-11
/time GET Utility to assist with management of time data. 2022-11-11
/user GET Inclusion of Custom fields. 2023-04-21
/user PUT Inclusion of Custom fields as optional fields. 2023-04-21
/user POST Inclusion of Custom fields as optional fields. 2023-04-21
/doorstate?lowbattery POST Enable email notifications based on specified threshold. 2023-04-21
/door POST Inclusion of Location ID as optional field. 2023-04-21
/acesslevel?search GET Added search endpoint for access levels. 2023-08-29
/acesslevel PUT Added update endpoint for access levels. 2023-08-29
HTTPS
All requests to the Lockt Cloud API must be done so over HTTPS. All other requests will be rejected.

URL
API Urls should be constructed as follows: https://cloudapi.lockt.com/api/[version]/[endpoint]
Example: https://cloudapi.lockt.com/api/v1/users

API Versions
Version URL reference
Version 1.1.0 v1


Authentication
In order to access the Lockt Cloud API, you must provide valid api credential headers with each request. Your credentials will be supplied as both an apiuser and apikey.

Authentication Header Example
"apiuser" : "9r8ehveyb5h8mnwwet4yf9ugjynz8pkn"
"apikey" : "hqx7wde64vwe987fvg6q4zaautrs3p7j"

Content-Type
All requests must present the Content-Type header with a value of 'application/json'.

Response Codes
Status Code Description
200 The request was processed successfully
400 There was an error processing your request. Details will be supplied in the response body.
401 Access to the indicated resource was denied. Details will be provided in the response body.
404 The resource was not found.
413 Request Entity Too Large. The request exceeds the maximum request size of 20M.
50X An unexpected error has occurred.


Expected Outputs
The following outputs may be encountered while processing create / update / delete calls.
Message Description
No data found or invalid JSON objects supplied. Could not parse input. The body of the request contained no data, or contained incorrectly structured data.
Batch size exceeds maximum of X objects. The supplied payload exceeds the currently allowed number of objects per batch.
Validation errors found. Batch has failed. Details provided. Some objects have failed validation. Details will be provided in the response body.
Unable to enumerate dependant record. Batch has been terminated and exception flagged. A communications error has occurred with your instance of Lockt SecureAccess.
Unable to locate template. Batch has been terminated and exception flagged. A communications error has occurred with your instance of Lockt SecureAccess.
The destination host is unreachable. A communications error has occurred with your instance of Lockt SecureAccess.
An Unexpected Error has occurred. Request has been terminated and exception flagged. A communications or processing error has occurred with your instance of Lockt SecureAccess.
Restriction Description
POST Operation Record Limit POST Operations are currently limited by default to 100 records per call. This may change per customer instance. Processing larger batches of records requires paging and processing in blocks of the allotted maximum size.
POST Operation Rate Limit Rate limiting is currently being implemented to prevent simultaneous and overlapping POST operations.
Max Request Size The maximum request size for all operations is 20M. Requests larger than 20M will return a 413 error.
All response calls to the API will return in a standard format as indicated below.

GET Requests (Read)
Node Description
data The body of the response return as an array of response objects.
errors Any processing or validation errors will appear in the data node, returned as an array of error objects.
Response Format
#Standard Response
{
    "data": {
        [array of response objects]
    }
}

#Error Response
{
    "data": {
        {"error":"error message"}
    }
}


POST Requests (Write)
Node Description
process summary The number of records submitted, processed, and errors.
errors Any processing or validation errors will appear in the errors node of the data object.
Response Format
                                            
                                            
#Result if the process succeeds and no errors
{
    "data": {
        "submitted": number of records submitted,
        "inserted": number of records inserted,
        "updated": number of records updated,
        "errors": number of errors encountered
    }
}

#Result if errors are encountered
{
    "result": [Array of text messages indicating what caused the problem],
    "errors": [Array of error objects that indicate what specifically occurred]
}

#Example errors encountered updating users
{
    "error": [
        "Non-Numeric card_num found: A8914",
        "Invalid email address found: rgreswell0@@@@gravatar.com"
    ],
    "input_data": {
        "id": -1,
        "id_num": "qjwi-880329359",
        "first_name": "Rhea",
        "last_name": "Greswell",
        "card_num": "A8914",
        "email": "rgreswell0@@@@gravatar.com",
        "phone": "8184365134",
        "access_effective": "2022-01-24 00:00:00",
        "access_expires": "2022-10-29 00:00:00",
        "pin": "0986",
        "enabled": false,
        "accesslevels": [
            {
                "id": 574
            }
        ]
    }
}
The following endpoints are available for use. Details on request and response specifics can be found in the subsequent sections.

Available Endpoints: 7


Endpoints


Endpoint Method Purpose Comments Status
/accesslevel GET List all access levels in the system. Released
/door GET List all access-controlled doors in the system. Released
/doorstate GET List door battery levels. Released
/schedule GET List all schedules in the system. Released
/user GET List all users in the system. Released
/user?installers GET List users with installer rights. Released
/user?id=[id] GET Read individual user with the specified id. id represents the Lockt SecureAccess internal id. Released
The following validations are performed on the indicated method and object.
Endpoint Method Submethod Field Validation
accesslevel POST INSERT door id Door ID is not duplicate
accesslevel POST INSERT door id Door ID is valid
accesslevel POST INSERT name Already exists in system
accesslevel POST INSERT name Missing or blank
accesslevel POST INSERT schedule id Schedule ID is valid
accesslevel PUT UPDATE door id Door ID is not duplicate
accesslevel PUT UPDATE door id Door ID is valid
accesslevel PUT UPDATE id Acess Level ID is valid
accesslevel PUT UPDATE name Field is Optional
accesslevel PUT UPDATE name Field is not Duplicate if supplied.
accesslevel PUT UPDATE schedule id Schedule ID is valid
credential DELETE id Id is not a Fob
credential DELETE id Id is valid
credential DELETE id Missing or blank
credential DELETE id Non-Numeric
door DELETE Id is valid
door DELETE id Missing or blank
door GET user_id user_id is valid, numeric and not blank
door POST name Already exists in system
door POST name Missing or blank
fob DELETE id Id is a Fob
fob DELETE id Missing or blank
fob DELETE id Non-Numeric
fob POST access_effective Valid date format
fob POST access_expires Valid date format
fob POST card_num Already exists in system
fob POST card_num Length versus system limit
fob POST card_num Non-Numeric
fob POST id_num Missing or blank
fob POST name Already exists in system
fob POST name Already exists in system
fob POST name Missing or blank
fob PUT access_effective Valid date format
fob PUT access_expires Valid date format
fob PUT card_num Already exists in system
fob PUT card_num Length versus system limit
fob PUT card_num Non-Numeric
fob PUT id_num Missing or blank
fob PUT name Already exists in system
fob PUT name Already exists in system
fob PUT name Missing or blank
location POST locationtype Id is valid
location POST locationtype Missing or blank
location POST name Already exists in system
location POST name Missing or blank
user DELETE id Id is valid
user DELETE id Missing or blank
user DELETE id Non-Numeric
user POST INSERT access_effective Valid date format
user POST INSERT access_expires Valid date format
user POST INSERT access_levels Duplicate Assigned Access Levels
user POST INSERT access_levels Id is valid
user POST INSERT card_num Already exists in system
user POST INSERT card_num Length versus system limit
user POST INSERT card_num Non-Numeric
user POST INSERT email Already exists in system
user POST INSERT email Missing or blank
user POST INSERT email Proper email format
user POST INSERT first_name Missing or blank
user POST INSERT id Missing or blank
user POST INSERT id Non-Numeric
user POST INSERT id_num Already exists in system
user POST INSERT id_num Missing or blank
user POST INSERT last_name Missing or blank
user POST INSERT phone Missing or blank
user POST INSERT phone Proper phone format
user POST INSERT pin Length versus system limit
user POST INSERT pin Missing or blank
user POST INSERT pin Non-Numeric
user POST UPDATE access_effective Valid date format
user POST UPDATE access_expires Valid date format
user POST UPDATE access_levels Duplicate Assigned Access Levels
user POST UPDATE access_levels Id is valid
user POST UPDATE card_num Length versus system limit
user POST UPDATE card_num Non-Numeric
user POST UPDATE card_num Used for update determination
user POST UPDATE email Already exists in system
user POST UPDATE email Missing or blank
user POST UPDATE email Proper email format
user POST UPDATE first_name Missing or blank
user POST UPDATE id Missing or blank
user POST UPDATE id Non-Numeric
user POST UPDATE id Used for update determination
user POST UPDATE id_num Missing or blank
user POST UPDATE id_num Used for update determination
user POST UPDATE last_name Missing or blank
user POST UPDATE phone Missing or blank
user POST UPDATE phone Proper phone format
user POST UPDATE pin Length versus system limit
user POST UPDATE pin Missing or blank
user POST UPDATE pin Non-Numeric

Purpose
List all access levels in the system.

REST Method
GET

Request URL
https://cloudapi.lockt.com/api/v1/accesslevel

Object Definition
Property Data Type Description
id integer The unique, system assigned id of the access level.
name string The name of the access level.
doors array An array of abbreviated Door objects containing Door ID and Schedule ID only.


Code Examples
import json
import requests

apiuser = "9r8ehveyb5h8mnwwet4yf9ugjynz8pkn"
apikey =  "hqx7wde64vwe987fvg6q4zaautrs3p7j"

headers = {"Content-type": "application/json", "apiuser":apiuser ,"apikey":apikey}
url = "https://cloudapi.lockt.com/api/v1/accesslevel"

r = requests.get(url, headers=headers)
data = r.json()
if r.status_code == 200:        
    #process the response    
else:
    #check for failed response


Example Response
{
    "data": [
        {
            "id": 208,
            "name": "Security",
            "doors": [
                {
                    "id": 983,
                    "name": "Office Door"
                },
                {
                    "id": 1087,
                    "name": "Front Door"
                }
            ]
        },
        {
            "id": 212,
            "name": "Administration"
        },
        {
            "id": 512,
            "name": "Cardholder"
        },
        {
            "id": 574,
            "name": "Housekeeping",
            "doors": [
                {
                    "id": 1087,
                    "name": "Front Door"
                }
            ]
        }
    ]
}

Purpose
List all access levels in the system by indicated name.

REST Method
GET

Request URL
https://cloudapi.lockt.com/api/v1/accesslevel?name=name

Object Definition
Property Data Type Description
id integer The unique, system assigned id of the access level.
name string The name of the access level.
doors array An array of abbreviated Door objects containing Door ID and Schedule ID only.


Code Examples
import json
import requests

apiuser = "9r8ehveyb5h8mnwwet4yf9ugjynz8pkn"
apikey =  "hqx7wde64vwe987fvg6q4zaautrs3p7j"

name = 'Security'

headers = {"Content-type": "application/json", "apiuser":apiuser ,"apikey":apikey}
url = "https://cloudapi.lockt.com/api/v1/accesslevel?name="+name

r = requests.get(url, headers=headers)
data = r.json()
if r.status_code == 200:        
    #process the response    
else:
    #check for failed response


Example Response
{
    "data": [
        {
            "id": 208,
            "name": "Security",
            "doors": [
                {
                    "id": 983,
                    "name": "Office Door"
                },
                {
                    "id": 1087,
                    "name": "Front Door"
                }
            ]
        }
    ]
}

Purpose
Search Access Levels and list results.

REST Method
GET

Request URL
https://cloudapi.lockt.com/api/v1/accesslevel?search=search_term

Note
Search term cannot contain wildcard characters (* %). The API will return an error if wildcard characters are detected.

Object Definition
Property Data Type Description
id integer The unique, system assigned id of the access level.
name string The name of the access level.
doors array An array of abbreviated Door objects containing Door ID and Schedule ID only.


Code Examples
import json
import requests

apiuser = "9r8ehveyb5h8mnwwet4yf9ugjynz8pkn"
apikey =  "hqx7wde64vwe987fvg6q4zaautrs3p7j"

search_term = 'Management'

headers = {"Content-type": "application/json", "apiuser":apiuser ,"apikey":apikey}
url = "https://cloudapi.lockt.com/api/v1/accesslevel?search="+search_term

r = requests.get(url, headers=headers)
data = r.json()
if r.status_code == 200:        
    #process the response    
else:
    #check for failed response


Example Response
{
    "data": [
        {
            "id": 208,
            "name": "Executive Management",
            "doors": [
                {
                    "id": 983,
                    "name": "Executive Conference Room"
                },
                {
                    "id": 1087,
                    "name": "Main Entrance"
                }
            ]
        },
        {
            "id": 208,
            "name": "Product Management",
            "doors": [
                {
                    "id": 852,
                    "name": "Lab Door"
                },
                {
                    "id": 1087,
                    "name": "Main Entrance"
                }
            ]
        }
    ]
}

Purpose
Update existing access level with supplied doors and schedules.

REST Method
PUT

Request URL
https://cloudapi.lockt.com/api/v1/accesslevel

Request Body Parameters
The body of the operation contains the following nodes:
Node Description
accesslevels An array of user objects to be created.
options Contains processing instructions for the operation.


Request Body Format
{
  "accesslevels": [array of access level objects],
  "options": {processing options}  
}


Object Definition
Property Data Type Description
id integer The ID of the Access Level being modified.
name string (Optional) The name of the access level.
doors array An array of abbreviated Door objects containing Door ID and Schedule ID only.


Processing Options Object Definition
Property Data Type Description
validate_fails_batch boolean If set to false, validation errors will be returned in the response body and records passing validation will be processed. If set to true, a validation error will fail the entire batch. This property defaults to true if not presented.


Example Request Body
{
  "accesslevels": [
    {
      "id": 78754,
      "name": "Access Level l",
      "doors": [
        {
          "id": 23456,
          "schedule_id": 567
        },
        {
          "id": 12345,
          "schedule_id": 789
        }
      ]
    }
  ]
}


Code Examples
import json
import requests

apiuser = '9r8ehveyb5h8mnwwet4yf9ugjynz8pkn'
apikey =  'hqx7wde64vwe987fvg6q4zaautrs3p7j'

headers = {'Content-type': 'application/json', 'apiuser':apiuser ,'apikey':apikey}
url = 'https://cloudapi.lockt.com/api/v1/accesslevel'

accesslevelnode = {}
accessleveldata = [{} for i in range(1)]

doordata = [{} for i in range(2)]
doordata[0] = {'id': 23456, 'schedule_id': 567}
doordata[1] = {'id': 12345, 'schedule_id': 789}
accessleveldata[0] = {'id':78754, 'doors': doordata}

accesslevelnode['accesslevels'] = accessleveldata

accesslevelnode['options'] = {'validate_fails_batch':'true'}
doorjson = json.dumps(doornode)

r = requests.put(url, data=doorjson, headers=headers)
data = r.json()
if r.status_code == 200:        
    #process the response    
else:
    #check for failed response

Purpose
Remove access levels from the system.

REST Method
DELETE

Request URL
https://cloudapi.lockt.com/api/v1/accesslevel

Request Body Parameters
The body of the operation contains the following nodes:
Node Description
accesslevels An array of user objects to be created.
options Contains processing instructions for the operation.


Request Body Format
{
  "accesslevels": [array of credential objects],
  "options": {processing options}  
}


Object Definition
Property Data Type Description
id integer The unique, system assigned id of the access level


Processing Options Object Definition
Property Data Type Description
validate_fails_batch boolean If set to false, validation errors will be returned in the response body and records passing validation will be processed. If set to true, a validation error will fail the entire batch. This property defaults to true if not presented.


Example Request Body
{
  "accesslevels": [
    {
        "id": 3456
    },
    {
        "id": 6578
    }
  ],
  "options": {
        "validate_fails_batch": "false"
  }
}


Code Examples
import json
import requests

apiuser = '9r8ehveyb5h8mnwwet4yf9ugjynz8pkn'
apikey =  'hqx7wde64vwe987fvg6q4zaautrs3p7j'

headers = {'Content-type': 'application/json', 'apiuser':apiuser ,'apikey':apikey}
url = 'https://cloudapi.lockt.com/api/v1/accesslevels'

acecsslevelnode = {}
acecssleveldata = [{} for i in range(2)]
acecssleveldata[0] = {'id':3456}
acecssleveldata[1] = {'id':6578}
acecsslevelnode['acecsslevels'] = acecssleveldata
acecsslevelnode['options'] = {'validate_fails_batch':'true'}
acecssleveljson = json.dumps(acecsslevelnode)

r = requests.delete(url, data=acecssleveljson, headers=headers)
data = r.json()
if r.status_code == 200:        
    #process the response    
else:
    #check for failed response


Response Body Format
{
    "data": {
        "submitted": number of records submitted,
        "deleted": number of records deleted,
        "errors": number of errors encountered
    }
}


Example Response
{
    "data": {
        "submitted": 2,
        "deleted": 2,
        "errors": 0
    }
}
-->

Warning: require_once(/var/www/cloudapi/assets/models/cloudaccess/_doors.php): failed to open stream: No such file or directory in /var/www/cloudapi/cloudaccess.php on line 120

Fatal error: require_once(): Failed opening required '/var/www/cloudapi/assets/models/cloudaccess/_doors.php' (include_path='.:/usr/share/php') in /var/www/cloudapi/cloudaccess.php on line 120