Key API Concepts

Base URL

The base URL for our API is https://api.nuki.io

Each endpoint is appended directly to the base URL, e.g. https://api.nuki.io/smartlock

Asynchronous

The Nuki REST API is asynchronous.

POST, PUT and DELETE requests will return a 200 or 204 response if the request payload was successfully validated. This does not mean that the action was successfully executed.

Once the server has received your API request, it will begin the process of obtaining a connection to the relevant Smart Lock, Smart Door or Opener, and will then execute the API request. This can sometimes take up to several seconds due to waking the device from a low power state, as well as any potential connectivity issues in the recipient device’s network.

GET requests are an exception. They will fetch the relevant data from the server and will return this data to you synchronously in the request body alongside a 200 status code.

How can you check the status of your POST, PUT and DELETE requests? There are 2 options at your disposal:

• Querying the relevant endpoint with a GET request to check if your action was successfully executed
• Use webhooks to be receive trigger notifications of any changes

Remote Access

Smartlocks and other devices require an internet connection to interact with the REST API.

Newer Smart Locks connect directly to the internet via the internal Wi-Fi antenna. If you haven’t already done so, you can configure the Wi-Fi settings of your device in the smartphone app.

Some older Smart Locks will require a bridge to connect to the internet. A bridge connects to the internet and relays communication to the connected devices via Bluetooth. The Opener requires a bridge if you wish to manage and operate it remotely.

Devices are operated via the “smartlock” endpoint

All Nuki devices are operated via the /smartlock endpoint, regardless of whether the device is a Smart Lock, Smart Door or Opener. That means if you want to fetch the configuration of a device or send a request to unlock/open, you always do so via the /smartlock endpoint.

The following types refer to the type property returned in the smartlock endpoint:

type	Device
0	Smart lock (1st/2nd Gen.)
1	Box
2	Opener
3	Smart door
4	Smart lock (3rd/4th Gen.)
5	Smart lock (5th Gen., Go/Pro/Ultra)

A detailed overview of our Smart Lock generations can be found in our help center.

Device IDs

Nuki uses a mixture of hexadecimal (hex) and integer IDs.

The Nuki REST API only uses integer IDs. If you are solely operating within the confinds of Nuki Web and the REST API, then you will only interact with integers. If you are looking at a specific Smart Lock ID in Nuki Web, you will find its ID in the URL.

You will find Hex IDs are used within the smartphone applications; you will first need to convert these to integers.

To find the Hex ID, open the Nuki app and tap on the desired device. Then open the device settings and navigate to “Features & Configuration” > “General”.

Converting HEX IDs to integers

Your HEX ID will look like so: 1A2B3C4D

Prior to converting, we need to prepend the device type to the HEX ID.

type	Device
0	Smart lock (1st/2nd Gen.)
1	Box
2	Opener
3	Smart door
4	Smart lock (3rd/4th Gen.)
0	Smart lock (5th Gen., Go/Pro/Ultra)

For example, if your device is one of the newest Smart Locks, you would prepend 5 to your ID, like so: 51A2B3C4D

You can then use a calculator to convert the HEX ID to a decimal/integer, resulting in an ID like this: 21913877581. You can now use this ID in your REST API requests.

Authorization Limits

Smartlocks and keypads have a limit on the number of authorizations that they can store.

Older devices can store 100 authorizations, whereas newer devices can store 200 authorizations.

Consider in your implementation to delete non-used and expired authorizations.

Keypad codes

When a keypad is connected to a device, you can create keypad codes to grant access instead of normal app invites.

A keypad code:

• is 6-digits in length
• uses the numbers 1-9 (cannot contain 0)
• cannot start 12
• must be unique on that keypad

Device States

The below refer to the state object which is returned in the smartlock endpoint response. Devices return a “state” object which provides you some information about the current state of the device, such as whether the door is unlocked.

Tip

Device triggered webhook: DEVICE_STATUS

Mode

The current operating mode of the device.

mode	Smart lock / Smart door	Opener
0	Unitialized	Unitialized
1	Pairing	Pairing
2	Door (Default)	Door (Default)
3	Failure *	Continuous
4	Maintenance	Maintenance
5	Test *	N/A

* Smart door only

State

The current state of the device.

state	Smart lock / Smart door	Opener
0	Uncalibrated / Not activated	Untrained
1	Locked	Online
2	Unlocking	N/A
3	Unlocked	”Ring to Open” active
4	Locking	N/A
5	Unlatched	Open
6	Unlocked (Lock’n’go)	N/A
7	Unlatching	Opening
253	Boot run	Boot run
254	Motor blocked	N/A
255	Undefined	Undefined

Trigger

The action which caused the state to change

trigger	Smart lock / Smart door	Opener
0	System (Bluetooth)	System (Bluetooth)
1	Manual	Manual
2	Button	Button
3	Automatic	Automatic
4	N/A	N/A
5	N/A	N/A
6	Auto Lock *	Continuous mode
7	External Accessory *	N/A

* Smart door only

Tip

Trigger types 4 and 5 are only used by the box. Trigger 4 refers to an action triggered via Nuki Web and trigger 5 from the smartphone app.

Last Action

The previous action that was performed on this device

lastAction	Smart lock / Smart door	Opener
1	Unlock	Activate “Ring to open”
2	Lock	Deactivate “Ring to open”
3	Unlatch	Electric Strike Actuation
4	Lock’n’go	N/A
5	Unlatch with Lock’n’go	N/A
6	N/A	Activate “Continuous Mode”
7	N/A	Deactivate “Continuous Mode”

Door State

This value represents the current state of the door

Note

You will only see the state of a door when you combine a smart lock with a door sensor. Door sensors are compatible from 3rd generation smart locks onwards.

doorState	Smart lock
0	Unavailable (i.e. no door sensor installed)
1	Deactivated
2	Door closed
3	Door open
4	Unknown
5	Calibrating

Device Actions

If you do not wish to use the simplified endpoints to lock or unlock your devices, you can define the following actions in the request body

Note

Please note that the simplified action endpoints are only supported by smartlocks, smart doors and openers. They are not supported by boxes.

Action	Smart lock, Smart door	Opener	Box
1	Unlock	Activate Ring to Open	Unlock
2	Lock	Deactivate Ring to Open	N/A
3	Unlatch	Electric Strike Actuation	N/A
4	Lock’n’go	N/A	N/A
5	Unlatch with Lock’n’go	N/A	N/A
6	N/A	Activate Continuous Mode	N/A
7	N/A	Deactivate Continuous Mode	N/A

Weekdays

Weekdays are set via bitmask values. Weekdays are specified when creating smart lock authorizations that are restricted to certain days of the week.

Weekday	Bitmask	Value
Monday	01000000	64
Tuesday	00100000	32
Wednesday	00010000	16
Thursday	00001000	8
Friday	00000100	4
Saturday	00000010	2
Sunday	00000001	1

To specify a single day, pass the value of that day. For example, granting access on a Wednesday would require a value of 16.

To specify a range, or a combination of days, add those days together

• Monday & Thursday: 64 + 8 = 72
• Monday - Friday: 64 + 32 + 16 + 8 + 4 = 124
• All week: 127 (alternatively do not set the allowedWeekDays value)

Time and Time Zones

All date and time values in our REST API are Coordinated Universal Time (UTC). They are passed in the following format:

YYYY-MM-DDT00:00:00.000Z

Here is excerpt from our smarlock/auth endpoint as an example:

"allowedFromDate": "2025-06-16T10:30:00.000Z"

Each device also supports a time zone. The user generally sets this time zone via the smartphone app while installing their smart lock. The list of IDs and their applicable offsets from UTC are displayed in the table below.

As a general rule, you shouldn’t update this time zone for a user’s device. This value only serves as a reference value, so that you can convert the UTC time into a time value appropriate to the user’s time zone in your application interface. These time zone values are set as an ID.

Helpers:

• Offset: The time offset from Coordinated Universal Time (UTC); multiple values provided for those time zones supporting DST
• DST: Whether this time zone supports Daylight Saving Time

Africa

ID	Time Zone	Offset	DST
0	Africa/Cairo	UTC+2	no
1	Africa/Lagos	UTC+1	no
2	Africa/Maputo	UTC+2	no
3	Africa/Nairobi	UTC+3	no

America

ID	Time Zone	Offset	DST
4	America/Anchorage	UTC-9/-8	yes
5	America/Buenos_Aires	UTC-3	no
6	America/Chicago	UTC-6/-5	yes
7	America/Denver	UTC-7/-6	yes
8	America/Halifax	UTC-4/-3	yes
9	America/Los_Angeles	UTC-8/-7	yes
10	America/Manaus	UTC-4	no
11	America/Mexico_City	UTC-6/-5	yes
12	America/New_York	UTC-5/-4	yes
13	America/Phoenix	UTC-7	no
14	America/Regina	UTC-6	no
15	America/Santiago	UTC-4/-3	yes
16	America/Sao_Paulo	UTC-3	no
17	America/St_Johns	UTC-3½/ -2½	yes

Asia

ID	Time Zone	Offset	DST
18	Asia/Bangkok	UTC+7	no
19	Asia/Dubai	UTC+4	no
20	Asia/Hong_Kong	UTC+8	no
21	Asia/Jerusalem	UTC+2/+3	yes
22	Asia/Karachi	UTC+5	no
23	Asia/Kathmandu	UTC+5¾	no
24	Asia/Kolkata	UTC+5½	no
25	Asia/Riyadh	UTC+3	no
26	Asia/Seoul	UTC+9	no
27	Asia/Shanghai	UTC+8	no
28	Asia/Tehran	UTC+3½	no
29	Asia/Tokyo	UTC+9	no
30	Asia/Yangon	UTC+6½	no

Australia

ID	Time Zone	Offset	DST
31	Australia/Adelaide	UTC+9½/10½	yes
32	Australia/Brisbane	UTC+10	no
33	Australia/Darwin	UTC+9½	no
34	Australia/Hobart	UTC+10/+11	yes
35	Australia/Perth	UTC+8	no
36	Australia/Sydney	UTC+10/+11	yes

Europe

ID	Time Zone	Offset	DST
37	Europe/Berlin	UTC+1/+2	yes
38	Europe/Helsinki	UTC+2/+3	yes
39	Europe/Istanbul	UTC+3	no
40	Europe/London	UTC+0/+1	yes
41	Europe/Moscow	UTC+3	no

Pacific

ID	Time Zone	Offset	DST
42	Pacific/Auckland	UTC+12/+13	yes
43	Pacific/Guam	UTC+10	no
44	Pacific/Honolulu	UTC-10	no
45	Pacific/Pago_Pago	UTC-11	no

From and To

When defining the from (allowedFromTime) and to (allowedUntilTime) values for a smart lock authorisation, the values are defined in minutes since midnight.

Example: You wish to allow access between 09:00 and 17:00.

09:00 is 9 hours past midnight, therefore 9 * 60 = 540. 17:00 is 1,020 minutes past midnight.

Paraphrasing the payload of the request, you would therefore send these values as follows:

{
    // ...
    "allowedFromTime": 540,
    "allowedUntilTime": 1020,
    // ...
}

Regions

We currently support devices for the following markets:

• EU
• Switzerland
• Nordics (Denmark, Sweden, Norway)
• United States of America

Smartlocks in each of these regions have different properties and mounting flows beyond the scope of this REST API documentation.

The functionality differences of these regions are as follows

• EU, Switzerland & Nordics
  • Full functionality
• United States of America
  • These devices do not support unlatch (the final, short turn which pulls the latch, opening the door)
  • Unlatch commands to these devices will return a 400 bad request error; use unlock instead