General Examples

Device

Unlock my smart lock

There are dedicated endpoints to unlock and lock your device.

Users of the Advanced API can also use the Advanced API endpoints for unlocking and locking. These provide the benefit of triggering webhooks to confirm whether the door was successfully unlocked or locked.

Check whether my smart lock is unlocked

Send a GET request to the smartlock endpoint. The response will contain a state object, included a self-named state property.

If you also have the optional door sensor installed, a doorState property will also tell you whether the door is open or closed.

Check if my device is online

Send a GET request to the smartlock endpoint.

The response will contain a serverState value. A value of 0 means the smart lock is online.

If the value is 4, the smart lock is offline and will not be reachable via the REST API.

DEVICE_AUTH webhooks will also include any changes to the serverState value.

Get my device settings

Send a GET request to the smartlock endpoint. You can either fetch all smart locks via this endpoint, or query a specific smart lock by appending the ID to the URL.

The response contains the config and the advancedConfig settings from your smart lock.

Check the battery level of my smart lock

Send a GET request to the smartlock endpoint. The response will contain a state object with a batteryCharge value. This is an estimated percentage value for the remaining battery level.

Additional values will inform you whether the smart lock battery level has fallen below a critical threshold and whether it is charging.

"state": {
    // ...
    "batteryCritical": false,
    "batteryCharging": false,
    "batteryCharge": 100,
    // ...
}

Invites and Access

This user is herein referred to as the accountUser.

There is no API triggered webhook for user creation, but newly created users are included in the DEVICE_AUTH type of device triggered webhooks. This will include the ID of the user you will require in the next step.

Create an app invite

When inviting someone to use a device, we create a smartlockAuth. This generates a code which the user can then redeem within the Nuki smartlock app.

This code is sent to the user via the e-mail address registered for the accountUser.

Send a PUT request with the following payload:

{
  "name": "Hello",
  "accountUserId": 123,
  "smartlockIds": [
    123456789
  ],
  "type": 0
}

The above is the minimum set of data required to create an app invite. You can expand the payload with optional parameters to specify on which weekdays the user can gain access, whether they can only gain access during specific dates or times, and whether the use should be able to operate the smart lock remotely.

{
  "name": "Hello",
  "allowedFromDate": "2026-07-12T09:00:00.000Z",
  "allowedUntilDate": "2026-07-15T14:00:00.000Z",
  "allowedWeekDays": 127,
  "allowedFromTime": 0,
  "allowedUntilTime": 0,
  "accountUserId": 123,
  "smartlockIds": [
    123456789
  ],
  "remoteAllowed": false,
  "smartActionsEnabled": true,
  "type": 0
}

Create a Keypad code

A keypad code is created like any other smartlock authorisation, with a couple of additional parameters set.

Firstly, to be sure if a keypad is connected to the relevant smart lock, you can send a GET request to the smartlock endpoint. This will return a config object which includes these 2 values:

"config": {
    // ...
    "keypadPaired": false,
    "keypad2Paired": true,
    // ...
}

If either keypadPaired or keypad2Paired are true, then a keypad is connected.

To create a keypad code, we will create a smartlockAuth. When doing so, it’s important to define that we are creating a keypad code, and not just a normal authorisation (i.e. app invite). This can be done by specifying the type as 13, alongside a code.

{
    "name": "Hello",
    "type": "13",
    "code": "352961",
}

Here are the guidelines on what a permitted keypad code may look like.

If you have 2 devices with separate keypads, such as an opener and a smart lock, you can register the one code on both devices to make access even simpler. To do, use the generic smartlockAuth endpoint (which is not specific to just one smart lock ID), and specify both device IDs in the payload as well.

Grant someone access for certain days or times of the week

When creating your smartlock authorisation, whether a normal app invite or a keypad code, you can also limit access to only certain periods of time.

To limit the days of the week on which access is granted, use the allowedWeekDays value. Check out our key concept on how weekdays are calculated as a bitmask value, and send this calculated value in the payload of your request.

Here is an example that limits access to Monday to Friday:

{
    // ...
    "allowedWeekDays": 124,
    // ...
}

To also limit the times of day the person can have access, use the allowedFromTime and allowedUntilTime values.

Check out the key concept on how from and to time values are calculated, and send these values in the payload of your request.

{
    // ...
    "allowedFromTime": 540, // 09:00
    "allowedToTime": 1020, // 17:00
    // ...
}

Grant someone access for a short period of time

You can limit access to a specific date range. This may be useful if you have contractors working in your property, or you have guests staying for a short period of time.

To do so, define the allowedFromDate and allowedUntilDate values when creating your smartlock authorisation.

These date values are defined in the payload of the request:

{
    // ...
    "allowedFromDate": "2026-02-20T06:00:00.000Z",
    "allowedUntilDate": "2026-02-24T18:00:00.000Z",
    // ...
}

The authorization will not work outside of this defined date range.