FORMAT: 1A HOST: https://graph.api.smartthings.com/api/smartapps/installations # Lock Manager API Allows you to manage your SmartThings locks, create and manage users remotely using RESTful API [Click here for instructions on how to install Lock Manager API](http://www.rboyapps.com/InstallLMAPI.htm) After installing the SmartApp, open the Lock Manager API on your SmartThings mobile app by clicking on the hamburger menu on the top left -> SmartApps -> Click on Lock Manager API 1. Select the _Lock(s)_ you want to manage/program remotely (make sure they aren't being used by any other apps to avoid conflicts) 1. Click on _Configure API_ to get your `ID` and `ACCESS_TOKEN` and `API URL` ![LMAPIMainPage,75%](https://www.rboyapps.com/images/LMAPIMain.png) Your `API URL` will look like `https://.api.smartthings.com/api/smartapps/installations/ID/api` and add `Authorization: Bearer ACCESS_TOKEN` to the header. The `` is the SmartThings server where your SmartApp is installed and can be found in the `API URL` on the _Configure API_ page of the SmartApp **NOTES:** 1. Keep your API URL safe and secure 1. ACCESS_TOKEN does not expire and you can generate a new one through the _Configure API_ page of your SmartApp 1. ID is unique for each installation instance of Lock Manager API (you can install the SmartApp multiple times) - If you're installing Lock Manager API more than once (or other apps like RLA or LUM), ensure sure that locks are not shared between the app installation instances to avoid programming conflicts 1. You can create/update/delete up to 100 users in a single API request # Group Create/Update Users ## Create/Update Users by Name or Slot [/{ID}/api] ### Permanent User [POST] + Parameters + ID (string) - Installation ID provided by the Lock Manager API SmartApp + Request (application/json) + Headers Authorization: Bearer ACCESS_TOKEN + Attributes + create (array, required) + (object) + name (string, required) - Name of user + type (*"Permanent"*, required) + user (number) - Slot number on lock to use. If not defined, automatically select next empty slot + code (string) - Code for user + notify (boolean) - Notify when code is used to unlock + notifyCount (number) - Notify only this many times (reset on each new programming command). 0 to set no limit + notifyModes (array[string]) - Notify only when Hub is any of these "modes". Empty array to notify in any mode + userLocks (array[string]) - Program user code only on these locks (names). Empty array to program on all locks + Body { "create": [ { "name": "Jack Ryan", "type": "Permanent", "user": "", "code": "1566", "notify": true, "notifyCount": 0, "notifyModes": [ "Home", "Away", "Night" ], "userLocks": [ "Front Door Lock", "Back Door Lock" ] } ] } + Response 201 (application/json) + Body { "processed": { "1": "Jack Ryan" }, "invalid": {} } ### One Time/Burner User [POST] + Parameters + ID (string) - Installation ID provided by the Lock Manager API SmartApp + Request (application/json) + Headers Authorization: Bearer ACCESS_TOKEN + Attributes + create (array, required) + (object) + name (string, required) - Name of user + type (*"One time"*, required) - Reactivated each time an API command is sent + user (number) - Slot number on lock to use. If not defined, automatically select next empty slot + code (string) - Code for user + notify (boolean) - Notify when code is used to unlock + notifyCount (number) - Notify only this many times (reset on each new programming command). 0 to set no limit + notifyModes (array[string]) - Notify only when Hub is any of these "modes". Empty array to notify in any mode + userLocks (array[string]) - Program user code only on these locks (names). Empty array to program on all locks + Body { "create": [ { "name": "Jack Ryan", "type": "One time", "user": "", "code": "1566", "notify": true, "notifyCount": 0, "notifyModes": [ "Home", "Away", "Night" ], "userLocks": [ "Front Door Lock", "Back Door Lock" ] } ] } + Response 201 (application/json) + Body { "processed": { "1": "Jack Ryan" }, "invalid": {} } ### Start and End Date/Time User [POST] + Parameters + ID (string) - Installation ID provided by the Lock Manager API SmartApp + Request (application/json) + Headers Authorization: Bearer ACCESS_TOKEN + Attributes + create (array, required) + (object) + name (string, required) - Name of user + type (*"Expire on"*, required) + user (number) - Slot number on lock to use. If not defined, automatically select next empty slot + expDate (string, required) - Expiration date in format yyyy-MM-dd + expTime (string, required) - Expiration time in format HH:mm + startDate (string) - Start date in format yyyy-MM-dd + startTime (string) - Start time in format HH:mm + code (string) - Code for user + notify (boolean) - Notify when code is used to unlock + notifyCount (number) - Notify only this many times (reset on each new programming command). 0 to set no limit + notifyModes (array[string]) - Notify only when Hub is any of these "modes". Empty array to notify in any mode + userLocks (array[string]) - Program user code only on these locks (names). Empty array to program on all locks + Body { "create": [ { "name": "Jack Ryan", "type": "Expire on", "user": "", "expDate": "2019-08-02", "expTime": "23:04", "startDate": "2019-06-01", "startTime": "03:05", "code": "1566", "notify": true, "notifyCount": 0, "notifyModes": [ "Home", "Away", "Night" ], "userLocks": [ "Front Door Lock", "Back Door Lock" ] } ] } + Response 201 (application/json) + Body { "processed": { "1": "Jack Ryan" }, "invalid": {} } ### Scheduled User (Weekly/Daily) [POST] + Parameters + ID (string) - Installation ID provided by the Lock Manager API SmartApp + Request (application/json) + Headers Authorization: Bearer ACCESS_TOKEN + Attributes + create (array, required) + (object) + name (string, required) - Name of user + type (*"Scheduled"*, required) + user (number) - Slot number on lock to use. If not defined, automatically select next empty slot + schedules (object, required) + A - Optional schedule A + dow (array, required) - List of the days of week for schedule to be active + (DOW) + startTime (string, required) - Start time in format HH:mm + endTime (string, required) - End time in format HH:mm + B - Optional schedule B + dow (array, required) - List of the days of week for schedule to be active + (DOW) + startTime (string, required) - Start time in format HH:mm + endTime (string, required) - End time in format HH:mm + C - Optional schedule C + dow (array, required) - List of the days of week for schedule to be active + (DOW) + startTime (string, required) - Start time in format HH:mm + endTime (string, required) - End time in format HH:mm + code (string) - Code for user + notify (boolean) - Notify when code is used to unlock + notifyCount (number) - Notify only this many times (reset on each new programming command). 0 to set no limit + notifyModes (array[string]) - Notify only when Hub is any of these "modes". Empty array to notify in any mode + userLocks (array[string]) - Program user code only on these locks (names). Empty array to program on all locks + Body { "create": [ { "name": "Jack Ryan", "type": "Scheduled", "user": "", "schedules": { "A": { "dow": [ "Monday", "Tuesday", "Friday" ], "startTime": "12:00", "endTime": "12:00" }, "B": { "dow": [ "All Week" ], "startTime": "14:09", "endTime": "14:09" }, "C": { "dow": [ "All Week", "Monday to Friday", "Saturday & Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday", "Sunday" ], "startTime": "14:09", "endTime": "14:09" } }, "code": "1566", "notify": true, "notifyCount": 0, "notifyModes": [ "Home", "Away", "Night" ], "userLocks": [ "Front Door Lock", "Back Door Lock" ] } ] } + Response 201 (application/json) + Body { "processed": { "1": "Jack Ryan" }, "invalid": {} } ### Modes Based User [POST] + Parameters + ID (string) - Installation ID provided by the Lock Manager API SmartApp + Request (application/json) + Headers Authorization: Bearer ACCESS_TOKEN + Attributes + create (array, required) + (object) + name (string, required) - Name of user + type (*"Modes"*, required) + user (number) - Slot number on lock to use. If not defined, automatically select next empty slot + modes (array[string], required) - List of Hub modes in which to activate the user + code (string) - Code for user + notify (boolean) - Notify when code is used to unlock + notifyCount (number) - Notify only this many times (reset on each new programming command). 0 to set no limit + notifyModes (array[string]) - Notify only when Hub is any of these "modes". Empty array to notify in any mode + userLocks (array[string]) - Program user code only on these locks (names). Empty array to program on all locks + Body { "create": [ { "name": "Jack Ryan", "type": "Modes", "user": "", "modes": [ "Home", "Night" ], "code": "1566", "notify": true, "notifyCount": 0, "notifyModes": [ "Home", "Away", "Night" ], "userLocks": [ "Front Door Lock", "Back Door Lock" ] } ] } + Response 201 (application/json) + Body { "processed": { "1": "Jack Ryan" }, "invalid": {} } ### Temporarily Disabled User [POST] + Parameters + ID (string) - Installation ID provided by the Lock Manager API SmartApp + Request (application/json) + Headers Authorization: Bearer ACCESS_TOKEN + Attributes + create (array, required) + (object) + name (string, required) - Name of user + type (*"Inactive"*, required) + user (number) - Slot number on lock to use. If not defined, automatically select next empty slot + code (string) - Code for user + notify (boolean) - Notify when code is used to unlock + notifyCount (number) - Notify only this many times (reset on each new programming command). 0 to set no limit + notifyModes (array[string]) - Notify only when Hub is any of these "modes". Empty array to notify in any mode + userLocks (array[string]) - Program user code only on these locks (names). Empty array to program on all locks + Body { "create": [ { "name": "Jack Ryan", "type": "Inactive", "user": "", "code": "1566", "notify": true, "notifyCount": 0, "notifyModes": [ "Home", "Away", "Night" ], "userLocks": [ "Front Door Lock", "Back Door Lock" ] } ] } + Response 201 (application/json) + Body { "processed": { "1": "Jack Ryan" }, "invalid": {} } ### Creating/updating multiple users in a single request [POST] + Parameters + ID (string) - Installation ID provided by the Lock Manager API SmartApp + Request (application/json) + Headers Authorization: Bearer ACCESS_TOKEN + Body { "create": [ { "name": "Jack Ryan", "type": "Permanent", "user": "", "code": "1566", "notify": true, "notifyCount": 0, "notifyModes": [ "Home", "Away", "Night" ], "userLocks": [ "Sample Door Lock" ] }, { "name": "Jennifer", "type": "One time", "user": 2, "code": "4535", "notify": true, "notifyCount": 0, "notifyModes": [], "userLocks": [] }, { "name": "Test3", "type": "Expire on", "user": 3, "expDate": "2019-08-02", "expTime": "23:04", "startDate": "2019-06-01", "startTime": "03:05", "code": "4528", "notify": true, "notifyCount": 0, "notifyModes": [], "userLocks": [] }, { "name": "Test4", "type": "Scheduled", "user": 4, "schedules": { "A": { "dow": [ "All Week", "Monday to Friday", "Saturday & Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday", "Sunday" ], "startTime": "14:09", "endTime": "14:09" } }, "code": "6754", "notify": true, "notifyCount": 0, "notifyModes": [], "userLocks": [] }, { "name": "Test5", "type": "Modes", "user": 5, "modes": [ "Home", "Night" ], "code": "1528", "notify": true, "notifyCount": 0, "notifyModes": [], "userLocks": [] }, { "name": "Test6", "type": "Inactive", "code": "8728", "notify": true, "notifyCount": 0, "notifyModes": [], "userLocks": [] } ] } + Response 201 (application/json) + Body { "processed": [ "1": "Jack Ryan", "2": "Jennifer", "3": "Test3", "4": "Test4", "5": "Test5", "6": "Test6" ], "invalid": { "Test6": "Not enough empty slots available. Maximum slots: 5" } } # Group Delete Users ## Delete Users by Name or Slot [/{ID}/api] ### Delete Users [POST] + Parameters + ID (string) - Installation ID provided by the Lock Manager API SmartApp + Request (application/json) + Headers Authorization: Bearer ACCESS_TOKEN + Attributes + delete (array, required) - List of users to delete (by name or slot number) + (number) - Slot number of user + (string) - Name of user + Body { "delete": [ "Jack Ryan", "Jennifer", 1, 2, 9999, 0, "Random name" ] } + Response 201 (application/json) + Body { "processed": [ "Jack Ryan", "Jennifer", "1", "2" ], "invalid": [ "9999", "0", "Random name" ] } # Group Get User Status ## Get Users by Name or Slot [/{ID}/api] ### Get Users [GET] + Parameters + ID (string) - Installation ID provided by the Lock Manager API SmartApp + Request (application/json) Response note: The programmed state for each user and lock is shown in `lockProgrammedState` which can contain the following values: `Pending program` - Awaiting code programming confirmation from lock `Pending deletion` - Awaiting code deletion confirmation from lock `Active` - Code programming is confirmed by lock `Inactive` - Code deletion is confirmed by lock `Failed` - Lock failed to respond even after configured number of retries + Attributes + get (array, required) - List of users to retrieve status and configuration (by name or slot number) + (number) - Slot number of user + (string) - Name of user + Headers Authorization: Bearer ACCESS_TOKEN + Body { "get": [ "Jack Ryan", "Jennifer", 3, 4, 5, 6, 9999, 0, "Random name" ] } + Response 201 (application/json) + Body { "processed": [ { "user": 1, "name": "Jack Ryan", "code": "1566", "type": "Permanent", "startDate": "", "expDate": "", "startTime": "", "expTime": "", "userLocks": [ "Front Door Lock", "Back Door Lock" ], "modes": [], "notifyModes": [ "Home", "Away", "Night" ], "schedules": { "A": { "startTime": "", "endTime": "", "dow": [] }, "B": { "startTime": "", "endTime": "", "dow": [] }, "C": { "startTime": "", "endTime": "", "dow": [] } }, "notify": true, "notifyCount": 0, "lockProgrammedState": { "Front Door Lock": "Active", "Back Door Lock": "Inactive" } }, { "user": 2, "name": "Jennifer", "code": "4535", "type": "One time", "startDate": "", "expDate": "", "startTime": "", "expTime": "", "userLocks": [ "Front Door Lock" ], "modes": [], "notifyModes": [], "schedules": { "A": { "startTime": "", "endTime": "", "dow": [] }, "B": { "startTime": "", "endTime": "", "dow": [] }, "C": { "startTime": "", "endTime": "", "dow": [] } }, "notify": true, "notifyCount": 0, "lockProgrammedState": { "Front Door Lock": "Pending program", "Back Door Lock": "Inactive" } }, { "user": 3, "name": "Test3", "code": "4528", "type": "Expire on", "startDate": "2019-06-01", "expDate": "2019-08-02", "startTime": "03:05", "expTime": "23:04", "userLocks": [ "Front Door Lock" ], "modes": [], "notifyModes": [], "schedules": { "A": { "startTime": "", "endTime": "", "dow": [] }, "B": { "startTime": "", "endTime": "", "dow": [] }, "C": { "startTime": "", "endTime": "", "dow": [] } }, "notify": true, "notifyCount": 0, "lockProgrammedState": { "Front Door Lock": "Pending deletion", "Back Door Lock": "Inactive" } }, { "user": 4, "name": "Test4", "code": "6754", "type": "Scheduled", "startDate": "", "expDate": "", "startTime": "", "expTime": "", "userLocks": [ "Front Door Lock" ], "modes": [], "notifyModes": [], "schedules": { "A": { "startTime": "12:00", "endTime": "12:00", "dow": [ "Monday", "Tuesday", "Friday" ] }, "B": { "startTime": "14:09", "endTime": "14:09", "dow": [ "All Week" ] }, "C": { "startTime": "14:09", "endTime": "14:09", "dow": [ "All Week", "Monday to Friday", "Saturday & Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday", "Sunday" ] } }, "notify": true, "notifyCount": 0, "lockProgrammedState": { "Front Door Lock": "Failed", "Back Door Lock": "Inactive" } }, { "user": 5, "name": "Test5", "code": "1528", "type": "Modes", "startDate": "", "expDate": "", "startTime": "", "expTime": "", "userLocks": [ "Front Door Lock" ], "modes": [ "Home", "Night" ], "notifyModes": [], "schedules": { "A": { "startTime": "", "endTime": "", "dow": [] }, "B": { "startTime": "", "endTime": "", "dow": [] }, "C": { "startTime": "", "endTime": "", "dow": [] } }, "notify": true, "notifyCount": 0, "lockProgrammedState": { "Front Door Lock": "Active", "Back Door Lock": "Inactive" } }, { "user": 6, "name": "Test6", "code": "8728", "type": "Inactive", "startDate": "", "expDate": "", "startTime": "", "expTime": "", "userLocks": [ "Front Door Lock" ], "modes": [], "notifyModes": [], "schedules": { "A": { "startTime": "", "endTime": "", "dow": [] }, "B": { "startTime": "", "endTime": "", "dow": [] }, "C": { "startTime": "", "endTime": "", "dow": [] } }, "notify": true, "notifyCount": 0, "lockProgrammedState": { "Front Door Lock": "Inactive", "Back Door Lock": "Inactive" } } ], "invalid": [ "9999", "0", "Random name" ] } #Group Lock & SmartApp Information ## Get Lock & SmartApp Configuration [/{ID}/api] ### Get Lock Names & Details [GET] + Parameters + ID (string) - Installation ID provided by the Lock Manager API SmartApp + Request (application/json) Response notes for each lock state: The last reported position for the lock which can contain the following values: `locked` - The lock is in locked position `unlocked` - The lock is in unlocked position `unknown` - The lock is jammed or cannot determine it's position battery: The last reported battery level (%) for the lock and is an integer between 0 and 100 connection: The connectivity status for the lock which can contain the following values: `online` - The platform is able to communicate with the lock `offline` - The hub cannot communicate with the lock (mesh problems, lock batteries etc) `hub disconnected` - The platform cannot communicate with the hub (power failure, internet connectivity etc) + Headers Authorization: Bearer ACCESS_TOKEN + Attributes + lock status (array, required) + Body { "lock status": [] } + Response 201 (application/json) + Body [ "Front Door Lock": { "state": "locked", "battery": 58, "connection": "online" }, "Back Door Lock": { "state": "unlocked", "battery": 100, "connection": "hub disconnected" }, "Patio Door Keypad": { "state": "unknown", "battery": 0, "connection": "offline" } ] ### List Hub Mode Names [GET] + Parameters + ID (string) - Installation ID provided by the Lock Manager API SmartApp + Request (application/json) + Headers Authorization: Bearer ACCESS_TOKEN + Attributes + list modes (array, required) + Body { "list modes": [] } + Response 201 (application/json) + Body [ "Night", "Away", "Home" ] ### Get Maximum Programmable Users [GET] + Parameters + ID (string) - Installation ID provided by the Lock Manager API SmartApp + Request (application/json) + Headers Authorization: Bearer ACCESS_TOKEN + Attributes + max users (array, required) - max users is limited to the lock with the lowest number of user slots amongst all locks selected in the SmartApp + Body { "max users": [] } + Response 201 (application/json) + Body [ 10 ] ### List Lock Names & State (deprecated) [GET] + Parameters + ID (string) - Installation ID provided by the Lock Manager API SmartApp + Request (application/json) + Headers Authorization: Bearer ACCESS_TOKEN + Attributes + list locks (array, required) + Body { "list locks": [] } + Response 201 (application/json) + Body [ "Front Door Lock": "locked", "Back Door Lock": "unlocked" ] # Group Lock Control ## Control Locks Remotely [/{ID}/api] ### Lock Commands [POST] + Parameters + ID (string) - Installation ID provided by the Lock Manager API SmartApp + Request (application/json) + Headers Authorization: Bearer ACCESS_TOKEN + Attributes + lock actions (array, required) + (object) + lock (string, required) - Name of lock + action (enum, required) - Command to execute + lock (string) - Lock the lock + unlock (string) - Unlock the lock + enableKeypad (string) - Enable keypad (if supported) + disableKeypad (string) - Disable keypad (if supported) + enableAutolock (string) - Enable AutoLock (if supported) + disableAutolock (string) - Disable AutoLock (if supported) + disableAudio (string) - Disable Audio (if supported) + enableAudio (string) - Enable Audio (if supported) + disableOneTouchLock (string) - Disable One Touch Locking (if supported) + enableOneTouchLock (string) - Enable One Touch Locking (if supported) + setAlarm (string) - Set Alarm Mode (if supported, valid mode parameters "off", "alert", "tamper", "forced") + setSensitivity (string) - Set Alarm Sensitivity Level (if supported, valid level parameters "lowest", "low", "medium", "high", "highest") + parameters (array) - List of command parameters if needed (see action for command specific parameters) + Body { "lock actions": [ { name: "Front Door Lock", action: "lock" } ] } + Response 201 (application/json) + Body { "processed": [ { "Front Door Lock": "lock" } ], "invalid": [ ] } + Request (application/json) + Body { "lock actions": [ { name: "Front Door Lock", action: "setAlarm", parameters: [ "tamper" ] }, { name: "Back Door Lock", action: "disableKeypad" }, { name: "Random Door Lock", action: "lock" } ] } + Response 201 (application/json) + Body { "processed": [ { "Front Door Lock": "setAlarm" } ], "invalid": [ { "Back Door Lock": "Unsupported action 'disableKeypad'" }, { "Random Door Lock": "Invalid lock" } ] } # Data Structures ## DOW (enum) + "All Week" + "Monday to Friday" + "Saturday & Sunday" + "Monday" + "Tuesday" + "Wednesday" + "Thursday" + "Friday" + "Saturday" + "Sunday"