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"
                      ]
                    }
                  }
                }
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
      }
  }
  

  {
    /// Summary:
    /// Provides the the type of event along with the corresponding event code on the device.
    
    public enum HistoryEventCode
    {
        /// Summary:
        /// Device was locked/unlocked by keypad (access code).
        
        LockedByKeyPad,
        UnlockedByKeyPad,

        /// Summary:
        /// Device locked/unlocked by thumbturn.
        
        LockedByThumbturn,
        UnlockedByThumbturn,

        /// Summary:
        /// Device locked by touchscreen (Schlage button).
        
        LockedBySchlageButton,

        /// Summary:
        /// Device locked/unlocked by Virtual Key.
        
        LockedByVirtualKey,
        UnlockedByVirtualKey,

        /// Summary:
        /// Device locked/unlocked by Timed delay feature.
        
        LockedByTime,
        UnlockedByTime,

        /// Summary:
        /// Device jammed during lock/unlock.
        
        LockJammed,

        /// Summary:
        /// Device disabled, too many failed access code attempts.
        
        KeypadDisabledInvalidCode,

        /// Summary:
        /// Device alarm triggered.
        
        AlarmTriggered,

        /// Summary:
        /// Added/Deleted access code to device.
        
        AccessCodeUserAdded,
        AccessCodeUserDeleted,

        /// Summary:
        /// Added/Removed user access to device.
        
        MobileUserAdded,
        MobileUserDeleted,

        /// Summary:
        /// User has been granted/revoked admin privelages to the device.
        
        AdminPrivilegeAdded,
        AdminPrivilegeDeleted,

        /// Summary:
        /// Device firmware updated.
        
        FirmwareUpdated,

        /// Summary:
        /// Device batteries are low.
        
        LowBatteryIndicated,
        
        /// Summary:
        /// Device batteries replaced.
        
        BatteryReplaced,

        /// Summary:
        /// Device alarm silenced.
        
        ForcedEntryAlarmSilenced,

        /// Summary:
        /// All device logs cleared.
        
        AllLogsCleared,

        /// Summary:
        /// Door sensor communication error.
        
        HallSensorCommError,

        /// Summary:
        /// FDR attempt on device failed.
        
        FdrFailed,

        /// Summary:
        /// Device batteries are critically low.
        
        CriticalBatteryState,

        /// Summary:
        /// All access codes on device removed.
        
        AllAccessCodeDeleted,

        /// Summary:
        /// Firmware update attempt failed.
        
        FirmwareUpdateFailed,

        /// Summary:
        /// Bluetooth firmware update attempt failed.
        
        BtFirmwareDownloadFailed,

        /// Summary:
        /// Wi-Fi firmware update attempt failed.
        
        WifiFirmwareDownloadFailed,

        /// Summary:
        /// Device keypad disconnected.
        
        KeypadDisconnected,

        /// Summary:
        /// Failed to add access code.
        
        UserDatabaseFailure,

        /// Summary:
        /// Device locked by Apple Home key.
        
        UnlockedByAppleHomeKey,

        /// Summary:
        /// Device unlocked by Apple Home key.
        
        LockedByAppleHomeKey,
    }
}
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"
                  ]
              }
          ]
      }
  }