Allegion Developer Portal

Schlage Home API v2

Welcome to the Schlage Home API v2 Platform Migration Guide. For those who are currently integrated to the Schlage Home API, we are introducing an updated Schlage Home API v2 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 v2 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. Additionally, you no longer 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.

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.

Events

Event schemas have been updated.

              {
                "$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"
                          }
                        ]
                      }
                    ]
                  },
                  "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"
                                ]
                              }
                            },
                            "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": "boolean"
                          }
                        },
                        "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"
                    ]
                  },
                  "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

Device response schemas no longer include “accessCodeLength”. This field now exists within the Access Code schema.

    {
      "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
Access Code schemas no longer include accessCodeLength within the root of the payload. This field has been moved into the details of each access code on the list. This also applies when fetching an individual access code. 

            {
              {
                "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": {}
                    }
                ]
            }
          }
Access Code request schemas have been updated to be consistent with response schemas 

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