Allegion Developer Portal

Schlage Home API

Welcome to the Schlage Home API Platform Guide. For those who are currently integrated to the Schlage Home API, we are introducing an updated Schlage Home API platform to simplify your integration as well as optimize the current processes. Here is a checklist that we have compiled for you to integrate with our new service. Please contact your Allegion representative for any additional questions.

1. Update the Schlage Home API URI

To ensure that those who are currently using the old Schlage Home API platform do not experience any downtime, the new Schlage Home API service is hosted on a new URI. In order to use this service, you will need to update the URI by simply removing the '/api' from the URLs your integration is using today: 

    https://api.allegion.com/schlage-home

2. API endpoint changes

Schlage Home API introduces changes to the API's POST, PUT, and DELETE requests. See below:

Devices API
If your integration has valid event subscriptions, webhook events will now provide updates on the status of these requests.POST, PUT, and DELETE requests to the device management endpoints will respond with a 202 ACCEPTED response.
Events API
You no longer need to register users for events or use the PUT Registration Refresh request to refresh the subscription every 24 hours. When your users subscribe, they will be given a valid access token. You do not need to subscribe to different event types. A valid subscription will receive all event types available to the Schlage account it's subscribed to. These events include:

  • Device Events such as: Lock and Unlock, Battery Low, Alarm Triggered, Keypad Lockout, and Network Connectivity
  • Device Command Events such as status updates for commands sent to the lock through the API
  • User Events such as: Global Signout, Integration Management ("Works With") and Account Management

For a full list of these event types, check out the Dev Portal Documentation.

Subscribing to Events
When you send over your endpoint, we require use of https (non-https urls will not be accepted). Upon receiving a request to subscribe, a validation OPTIONS request will be sent to verify the endpoint you provided. Please ensure your server can accept these types of requests.

NOTE: The validation request must be responded to within 30 seconds or the subscription will not be created.

The validation request will contain a header WebHook-Request-Origin. In your response to the validation request, please include the header WebHook-Allowed-Origin with the value contained in the WebHook-Request-Origin header and a successful HTTP response code (2xx).

Upon validation of the webhook endpoint, a subscription will be created, and a 200 OK response will be returned.

If a user cancels their integration, the event subscription for that user will be deleted, and you will no longer receive events for that user.

Schemas

Schemas reflect a more dynamic approach to utilizing our platform. These schemas are subject to change to reflect ongoing improvements to our platform, please follow our Release Notes for such updates.

Events

                {
                  "$schema": "https://json-schema.org/draft/2020-12/schema",
                  "type": "object",
                  "allOf": [
                    {
                      "type": "object",
                      "properties": {
                        "eventId": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "deviceId": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "uuid"
                        },
                        "time": {
                          "type": "string"
                        },
                        "version": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "eventId",
                        "time",
                        "version"
                      ]
                    },
                    {
                      "oneOf": [
                        {
                          "$ref": "#/$defs/deviceUpdate"
                        },
                        {
                          "$ref": "#/$defs/accessCodeUpdate"
                        },
                        {
                          "$ref": "#/$defs/commandUpdate"
                        },
                        {
                          "$ref": "#/$defs/userDevicesUpdate"
                        },
                        {
                          "$ref": "#/$defs/clientUpdate"
                        }
                      ]
                    }
                  ],
                  "$defs": {
                    "deviceUpdate": {
                      "allOf": [
                        {
                          "type": "object",
                          "properties": {
                            "eventType": {
                              "const": "DeviceUpdate"
                            }
                          }
                        },
                        {
                          "oneOf": [
                            {
                              "$ref": "#/$defs/deviceLockStateChanged"
                            },
                            {
                              "$ref": "#/$defs/deviceBatteryStateChanged"
                            },
                            {
                              "$ref": "#/$defs/deviceConnectivityStateChanged"
                            },
                            {
                              "$ref": "#/$defs/deviceAlarmStateChanged"
                            },
                            {
                              "$ref": "#/$defs/deviceKeypadLockoutStateChanged"
                            },
                            {
                              "$ref": "#/$defs/deviceIncorrectAccessCodeEntered"
                            }
                          ]
                        }
                      ]
                    },
                    "deviceLockStateChanged": {
                      "type": "object",
                      "properties": {
                        "trigger": {
                          "const": "DeviceLockStateChanged"
                        },
                        "data": {
                          "type": "object",
                          "properties": {
                            "lockState": {
                              "type": "string",
                              "enum": [
                                "Unlocked",
                                "Locked",
                                "Jammmed",
                                "Unknown",
                                "MotorFail",
                                "PassageMode",
                                "Deadlocked"
                              ]
                            },
                            "accessor": {
                              "type": [
                                "object",
                                "null"
                              ],
                              "properties": {
                                "id": {
                                  "type": [
                                    "string",
                                    "null"
                                  ],
                                  "format": "uuid"
                                },
                                "friendlyName": {
                                  "type": [
                                    "string",
                                    "null"
                                  ]
                                },
                                "accessType": {
                                  "type": "string",
                                  "enum": [
                                    "AccessCode",
                                    "VirtualKey",
                                    "AutoRelock",
                                    "Thumbturn",
                                    "1TouchLocking",
                                    "AppleHome",
                                    "AppleHomeNFC",
                                    "ScheduledLock",
                                    "UnlockButton",
                                    "LockButton",
                                    "AccessTypeUnavailable"
                                  ]
                                }
                              },
                              "required": [
                                "accessType"
                              ]
                            }
                          },
                          "required": [
                            "lockState"
                          ]
                        }
                      },
                      "required": [
                        "trigger",
                        "data"
                      ]
                    },
                    "deviceBatteryStateChanged": {
                      "type": "object",
                      "properties": {
                        "trigger": {
                          "const": "DeviceBatteryStateChanged"
                        },
                        "data": {
                          "type": "object",
                          "properties": {
                            "batteryState": {
                              "type": "string",
                              "enum": [
                                "Normal",
                                "Low",
                                "CriticallyLow",
                                "Unknown"
                              ]
                            },
                            "percentageBatteryLevel": {
                              "type": "integer",
                              "minimum": 0,
                              "maximum": 100
                            }
                          },
                          "required": [
                            "batteryState",
                            "percentageBatteryLevel"
                          ]
                        }
                      },
                      "required": [
                        "trigger",
                        "data"
                      ]
                    },
                    "deviceConnectivityStateChanged": {
                      "type": "object",
                      "properties": {
                        "trigger": {
                          "const": "DeviceConnectivityStateChanged"
                        },
                        "data": {
                          "type": "object",
                          "properties": {
                            "connected": {
                              "type": "string"
                            }
                          },
                          "required": [
                            "connected"
                          ]
                        }
                      },
                      "required": [
                        "trigger",
                        "data"
                      ]
                    },
                    "deviceAlarmStateChanged": {
                      "type": "object",
                      "properties": {
                        "trigger": {
                          "const": "DeviceAlarmStateChanged"
                        },
                        "data": {
                          "type": "object",
                          "properties": {
                            "inAlarm": {
                              "type": "boolean"
                            }
                          },
                          "required": [
                            "inAlarm"
                          ]
                        }
                      },
                      "required": [
                        "trigger",
                        "data"
                      ]
                    },
                    "deviceKeypadLockoutStateChanged": {
                      "type": "object",
                      "properties": {
                        "trigger": {
                          "const": "DeviceKeypadLockoutStateChanged"
                        },
                        "data": {
                          "type": "object",
                          "properties": {
                            "lockedOut": {
                              "type": "boolean"
                            }
                          },
                          "required": [
                            "lockedOut"
                          ]
                        }
                      },
                      "required": [
                        "trigger",
                        "data"
                      ]
                    },
                    "deviceIncorrectAccessCodeEntered": {
                      "type": "object",
                      "properties": {
                        "trigger": {
                          "const": "DeviceIncorrectAccessCodeEntered"
                        },
                        "data": {
                          "type": "object",
                          "properties": {
                            "enteredAccessCode": {
                              "type": "string"
                            }
                          },
                          "required": [
                            "enteredAccessCode"
                          ]
                        }
                      },
                      "required": [
                        "trigger",
                        "data"
                      ]
                    },
                    "accessCodeUpdate": {
                      "type": "object",
                      "properties": {
                        "eventType": {
                          "const": "AccessCodeUpdate"
                        },
                        "trigger": {
                          "type": "string",
                          "enum": [
                            "AccessCodeAdded",
                            "AccessCodeUpdated",
                            "AccessCodeDeleted"
                          ]
                        },
                        "data": {
                          "type": "object",
                          "properties": {
                            "accessCodeId": {
                              "type": "string",
                              "format": "uuid"
                            },
                            "name": {
                              "type": "string"
                            },
                            "code": {
                              "type": "string"
                            },
                            "accessCodeLength": {
                              "type": "integer"
                            },
                            "readOnly": {
                              "type": "boolean"
                            },
                            "scheduleType": {
                              "type": "string",
                              "enum": [
                                "Always",
                                "Recurring",
                                "Temporary"
                              ]
                            },
                            "scheduleDetails": {
                              "type": "object",
                              "properties": {
                                "schedules": {
                                  "type": "array",
                                  "items": {
                                    "type": "object",
                                    "properties": {
                                      "startTime": {
                                        "type": "string"
                                      },
                                      "endTime": {
                                        "type": "string"
                                      },
                                      "activeWeekDays": {
                                        "type": "array",
                                        "items": {
                                          "type": "string",
                                          "enum": [
                                            "Sunday",
                                            "Monday",
                                            "Tuesday",
                                            "Wednesday",
                                            "Thursday",
                                            "Friday",
                                            "Saturday"
                                          ]
                                        }
                                      }
                                    },
                                    "required": [
                                      "startTime",
                                      "endTime",
                                      "activeWeekDays"
                                    ]
                                  }
                                }
                              }
                            }
                          },
                          "required": [
                            "accessCodeId",
                            "name",
                            "code",
                            "accessCodeLength",
                            "readOnly",
                            "scheduleDetails",
                            "scheduleType"
                          ]
                        }
                      },
                      "required": [
                        "eventType",
                        "trigger",
                        "data"
                      ]
                    },
                    "commandUpdate": {
                      "allOf": [
                        {
                          "type": "object",
                          "properties": {
                            "eventType": {
                              "const": "CommandUpdate"
                            }
                          },
                          "required": [
                            "eventType"
                          ]
                        },
                        {
                          "oneOf": [
                            {
                              "$ref": "#/$defs/commandSucceeded"
                            },
                            {
                              "$ref": "#/$defs/commandFailed"
                            },
                            {
                              "$ref": "#/$defs/commandTimedOut"
                            }
                          ]
                        }
                      ]
                    },
                    "commandSucceeded": {
                      "type": "object",
                      "properties": {
                        "trigger": {
                          "const": "CommandSucceeded"
                        },
                        "data": {
                          "$ref": "#/$defs/commandData"
                        }
                      }
                    },
                    "commandFailed": {
                      "type": "object",
                      "properties": {
                        "trigger": {
                          "const": "CommandFailed"
                        },
                        "data": {
                          "allOf": [
                            {
                              "type": "object",
                              "properties": {
                                "statusCode": {
                                  "type": "integer"
                                },
                                "errorCode": {
                                  "type": "integer"
                                },
                                "errorMessage": {
                                  "type": "string"
                                }
                              }
                            },
                            {
                              "$ref": "#/$defs/commandData"
                            }
                          ]
                        }
                      }
                    },
                    "commandTimedOut": {
                      "type": "object",
                      "properties": {
                        "trigger": {
                          "const": "CommandTimedOut"
                        },
                        "data": {
                          "$ref": "#/$defs/commandData"
                        }
                      }
                    },
                    "commandData": {
                      "type": "object",
                      "properties": {
                        "commandId": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "commandType": {
                          "type": "string",
                          "enum": [
                            "SetLockState",
                            "AddAccessCode",
                            "UpdateAccessCode",
                            "DeleteAccessCode",
                            "DeleteAllAccessCodes"
                          ]
                        },
                        "accessCodeId": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "uuid"
                        },
                        "requestedLockState": {
                          "type": [
                            "string",
                            "null"
                          ]
                        }
                      },
                      "required": [
                        "commandId",
                        "commandType"
                      ]
                    },
                    "userDevicesUpdate": {
                      "type": "object",
                      "properties": {
                        "eventType": {
                          "const": "UserDevicesUpdate"
                        },
                        "trigger": {
                          "type": "string",
                          "enum": [
                            "DeviceAdded",
                            "DeviceNameChanged",
                            "DeviceRemoved"
                          ]
                        },
                        "data": {
                          "type": "object",
                          "properties": {
                            "name": {
                              "type": [
                                "string",
                                "null"
                              ]
                            }
                          },
                          "required": [
                            "name"
                          ]
                        }
                      },
                      "required": [
                        "eventType",
                        "trigger",
                        "data"
                      ]
                    },
                    "clientUpdate": {
                      "type": "object",
                      "properties": {
                        "eventType": {
                          "const": "ClientEvent"
                        },
                        "trigger": {
                          "type": "string",
                          "enum": [
                            "GlobalSignOut",
                            "IntegrationSignOut"
                          ]
                        },
                        "userId": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "uuid"
                        },
                        "clientId": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "uuid"
                        }
                      },
                      "required": [
                        "eventType",
                        "trigger"
                      ]
                    }
                  }
                }
"$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "allOf": [ { "type": "object", "properties": { "eventId": { "type": "string", "format": "uuid" }, "deviceId": { "type": [ "string", "null" ], "format": "uuid" }, "time": { "type": "string", "format": "date-time" }, "version": { "type": "string" } }, "required": [ "eventId", "time", "version" ] }, { "oneOf": [ { "$ref": "#/$defs/deviceUpdate" }, { "$ref": "#/$defs/accessCodeUpdate" }, { "$ref": "#/$defs/commandUpdate" }, { "$ref": "#/$defs/userDevicesUpdate" }, { "$ref": "#/$defs/clientUpdate" } ] } ], "$defs": { "deviceUpdate": { "allOf": [ { "type": "object", "properties": { "eventType": { "const": "DeviceUpdate" } } }, { "oneOf": [ { "$ref": "#/$defs/deviceLockStateChanged" }, { "$ref": "#/$defs/deviceBatteryStateChanged" }, { "$ref": "#/$defs/deviceConnectivityStateChanged" }, { "$ref": "#/$defs/deviceAlarmStateChanged" }, { "$ref": "#/$defs/deviceKeypadLockoutStateChanged" }, { "$ref": "#/$defs/deviceIncorrectAccessCodeEntered" } ] } ] }, "deviceLockStateChanged": { "type": "object", "properties": { "trigger": { "const": "DeviceLockStateChanged" }, "data": { "type": "object", "properties": { "lockState": { "type": "string", "enum": [ "Unlocked", "Locked", "Jammmed", "Unknown" ] }, "accessor": { "type": [ "object", "null" ], "properties": { "id": { "type": [ "string", "null" ], "format": "uuid" }, "friendlyName": { "type": [ "string", "null" ] }, "accessType": { "type": "string", "enum": [ "AccessCode", "VirtualKey", "AutoRelock", "Thumbturn", "1TouchLocking", "AppleHome", "AppleHomeNFC", "ScheduledLock", "UnlockButton", "LockButton", "AccessTypeUnavailable" ] } }, "required": [ "accessType" ] } }, "required": [ "lockState" ] } }, "required": [ "trigger", "data" ] }, "deviceBatteryStateChanged": { "type": "object", "properties": { "trigger": { "const": "DeviceBatteryStateChanged" }, "data": { "type": "object", "properties": { "batteryState": { "type": "string", "enum": [ "Normal", "Low", "CriticallyLow", "Unknown" ] }, "percentageBatteryLevel": { "type": "integer", "minimum": 0, "maximum": 100 } }, "required": [ "batteryState", "percentageBatteryLevel" ] } }, "required": [ "trigger", "data" ] }, "deviceConnectivityStateChanged": { "type": "object", "properties": { "trigger": { "const": "DeviceConnectivityStateChanged" }, "data": { "type": "object", "properties": { "connected": { "type": "string" } }, "required": [ "connected" ] } }, "required": [ "trigger", "data" ] }, "deviceAlarmStateChanged": { "type": "object", "properties": { "trigger": { "const": "DeviceAlarmStateChanged" }, "data": { "type": "object", "properties": { "inAlarm": { "type": "boolean" } }, "required": [ "inAlarm" ] } }, "required": [ "trigger", "data" ] }, "deviceKeypadLockoutStateChanged": { "type": "object", "properties": { "trigger": { "const": "DeviceKeypadLockoutStateChanged" }, "data": { "type": "object", "properties": { "lockedOut": { "type": "boolean" } }, "required": [ "lockedOut" ] } }, "required": [ "trigger", "data" ] }, "deviceIncorrectAccessCodeEntered": { "type": "object", "properties": { "trigger": { "const": "DeviceIncorrectAccessCodeEntered" }, "data": { "type": "object", "properties": { "enteredAccessCode": { "type": "string" } }, "required": [ "enteredAccessCode" ] } }, "required": [ "trigger", "data" ] }, "accessCodeUpdate": { "type": "object", "properties": { "eventType": { "const": "AccessCodeUpdate" }, "trigger": { "type": "string", "enum": [ "AccessCodeAdded", "AccessCodeUpdated", "AccessCodeDeleted" ] }, "data": { "type": "object", "properties": { "accessCodeId": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "code": { "type": "string" }, "accessCodeLength": { "type": "integer" }, "readOnly": { "type": "boolean" }, "scheduleType": { "type": "string", "enum": [ "Always", "Recurring", "Temporary" ] }, "scheduleDetails": { "type": "object", "properties": { "schedules": { "type": "array", "items": { "type": "object", "properties": { "startTime": { "type": "string" }, "endTime": { "type": "string" }, "activeWeekDays": { "type": "array", "items": { "type": "string", "enum": [ "Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday" ] } } }, "required": [ "startTime", "endTime", "activeWeekDays" ] } } } } }, "required": [ "accessCodeId", "name", "code", "accessCodeLength", "readOnly", "scheduleDetails", "scheduleType" ] } }, "required": [ "eventType", "trigger", "data" ] }, "commandUpdate": { "allOf": [ { "type": "object", "properties": { "eventType": { "const": "CommandUpdate" } }, "required": [ "eventType" ] }, { "oneOf": [ { "$ref": "#/$defs/commandSucceeded" }, { "$ref": "#/$defs/commandFailed" }, { "$ref": "#/$defs/commandTimedOut" } ] } ] }, "commandSucceeded": { "type": "object", "properties": { "trigger": { "const": "CommandSucceeded" }, "data": { "$ref": "#/$defs/commandData" } } }, "commandFailed": { "type": "object", "properties": { "trigger": { "const": "CommandFailed" }, "data": { "allOf": [ { "type": "object", "properties": { "statusCode": { "type": "integer" }, "errorCode": { "type": "integer" }, "errorMessage": { "type": "string" } } }, { "$ref": "#/$defs/commandData" } ] } } }, "commandTimedOut": { "type": "object", "properties": { "trigger": { "const": "CommandTimedOut" }, "data": { "$ref": "#/$defs/commandData" } } }, "commandData": { "type": "object", "properties": { "commandId": { "type": "string", "format": "uuid" }, "commandType": { "type": "string", "enum": [ "SetLockState", "AddAccessCode", "UpdateAccessCode", "DeleteAccessCode", "DeleteAllAccessCodes" ] }, "accessCodeId": { "type": [ "string", "null" ], "format": "uuid" }, "requestedLockState": { "type": [ "string", "null" ] } }, "required": [ "commandId", "commandType" ] }, "userDevicesUpdate": { "type": "object", "properties": { "eventType": { "const": "UserDevicesUpdate" }, "trigger": { "type": "string", "enum": [ "DeviceAdded", "DeviceNameChanged", "DeviceRemoved" ] }, "data": { "type": "object", "properties": { "name": { "type": [ "string", "null" ] } }, "required": [ "name" ] } }, "required": [ "eventType", "trigger", "data" ] }, "clientUpdate": { "type": "object", "properties": { "eventType": { "const": "ClientEvent" }, "trigger": { "type": "string", "enum": [ "GlobalSignOut", "IntegrationSignOut" ] }, "userId": { "type": [ "string", "null" ], "format": "uuid" }, "clientId": { "type": [ "string", "null" ], "format": "uuid" } }, "required": [ "eventType", "trigger" ] } } }
Devices

    {
      "id": "",
      "name": "",
      "type": "be489wifi",
      "lockState": "Unlocked",
      "batteryState": "Normal",
      "modelName": "be489WB",
      "serialNumber": "",
      "percentageBatteryLevel": 91,
      "connected": true,
      "lastConnectedToCloud": "2024-05-16T18:10:42Z",
      "lastUpdated": "2024-05-16T18:10:42Z",
      "created": "2024-05-16T15:10:39Z",
      "timezoneOffset": "-06:00",
      "firmwareVersion": "12.00.00815524",
      "features": {
          "vlac": true,
          "activityAlarm": true
      }
  }
Access Codes

            {
              {
                "accessCodes": [
                    {
                        "accessCodeId": "",
                        "name": "",
                        "code": "1629",
                        "accessCodeLength": 4,
                        "readOnly": false,
                        "scheduleType": "Recurring",
                        "scheduleDetails": {
                            "schedules": [
                                {
                                    "startTime": "00:01",
                                    "endTime": "23:59",
                                    "activeWeekDays": [
                                        "Monday",
                                        "Tuesday",
                                        "Wednesday"
                                    ]
                                }
                            ]
                        }
                    },
                    {
                        "accessCodeId": "",
                        "name": "",
                        "code": "2345",
                        "accessCodeLength": 4,
                        "readOnly": false,
                        "scheduleType": "Temporary",
                        "scheduleDetails": {
                            "startDateTime": "20221111T22:45",
                            "endDateTime": "20221114T17:15"
                        }
                    },
                    {
                        "accessCodeId": "",
                        "name": "",
                        "code": "5555",
                        "accessCodeLength": 4,
                        "readOnly": false,
                        "scheduleType": "Always",
                        "scheduleDetails": {}
                    }
                ]
            }
          }
          

    {
      "name": "",
      "accessCode": "1629",
      "scheduleType": "Recurring",
      "scheduleDetails": {
          "schedules": [
              {
                  "startTime": "00:01",
                  "endTime": "23:59",
                  "activeWeekDays": [
                      "Monday",
                      "Tuesday",
                      "Wednesday"
                  ]
              }
          ]
      }
  }