Web API Example: Manage PIN-Codes for your Nuki Keypad

Nuki APIs Web API
, ,
1

Authenticate

See Authentification. Use the access token as e.g. ACCESS_TOKEN.

Get the smartlock ID

curl -X GET --header 'Accept: application/json' --header 'Authorization: Bearer ACCESS_TOKEN' 
'https://api.nuki.io/smartlock'

Create a new Keypad PIN

You have to set a PIN_NAME (string; up to 20 characters) and a PIN_CODE (6 digits from 1-9 without 0 (zero); not starting with ‘12’ AND not already used by another PIN_NAME (each PIN may only occur once in the system!).

curl -X PUT --header 'Content-Type: application/json' --header 'Accept: application/json' --header 
'Authorization: Bearer ACCESS_TOKEN' -d '{ "name": "PIN_NAME", 
"type": 13, "code": PIN_CODE }' 
'https://api.nuki.io/smartlock/SMARTLOCK_ID/auth'

Get the PIN ID

If the PIN is created correctly you get an empty reply. In order to access the PIN later on you got to get its authId:

curl -X GET --header 'Accept: application/json' --header 'Authorization: Bearer ACCESS_TOKEN' 
'https://api.nuki.io/smartlock/SMARTLOCK_ID/auth'

Use the id of the auth for the PIN_NAME you created as PIN_ID.

Edit a PIN

You can update a PIN by overwriting values for a existing PIN_ID.

curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' --header 
'Authorization: Bearer ACCESS_TOKEN' -d '{ "name": "NEW_KEY_NAME", 
"code": "NEW_PIN_CODE" }' 
'https://api.nuki.io/smartlock/SMARTLOCK_ID/auth/PIN_ID'

Deactivate a PIN

Just update the PIN with “enable”: false:

curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' --header 
'Authorization: Bearer ACCESS_TOKEN' -d '{ "enable": false }' 
'https://api.nuki.io/smartlock/SMARTLOCK_ID/auth/PIN_ID'

Delete a PIN

You can completely delete a PIN:

curl -X DELETE --header 'Accept: application/json' --header 'Authorization: Bearer ACCESS_TOKEN' 
'https://api.nuki.io/smartlock/SMARTLOCK_ID/auth/PIN_ID'
This topic will contain a table of contents
2 Likes
2

I can create and remove new Keypad-Codes but i dont find a way to set the parameters e.g. allowedFromDate or allowedUntilDate.

My request is
curl -X POST --header ‘Content-Type: application/json’ --header ‘Accept: application/json’ --header
‘Authorization: Bearer ACCESS_TOKEN’ -d ‘{ “allowedFromDate”:“2019-02-01T15:00:00.000Z”}’
‘https://api.nuki.io/smartlock/SMARTLOCK_ID/auth/PIN_ID’

and the answer
{“code”:422,“description”:“The server understands the content type of the reques
t entity and the syntax of the request entity is correct but was unable to proce
ss the contained instructions”,“homeRef”:"/",“reasonPhrase”:“Unprocessable Entit
y”,“uri”:“http://www.webdav.org/specs/rfc2518.html#STATUS_422”}

Is it not possible to set a time-window for Keypad Codes ? On the web-platform i can set this parameters.

best regards, Tom

3

Hey Tom.
It is in fact possible to set a time window. Here is a example how im using the api to update the timewindow for the existing keycode:
{"name": "Test", "type": 13, "code": 999999, "allowedFromTime": 1099, "allowedUntilTime": 1129, "allowedFromDate": "2019-01-29T23:00:00.000Z", "allowedUntilDate": "2019-01-30T22:59:59.999Z","allowedWeekDays": 0}

As I unterstand the documentation, you must provide all values even if you just setting the timewindow.

Best regards,
Niklas

1 Like
4

Hey Niklas.
Thanks for the fast response. My first mistake was to use curl with windows so i had to backslash the quotes for the extra parameters. By the creation only of the keycode it has worked without backslash so its a little bit tricky to find this mistake. I tried out your code and it worked fine with the date and the allowedWeekDays and i can see all in the webplatform but the allowed time i can see only if i read it from the lock with the api. The Web-Platform don’t show it. I also found out that if you want to change e.g. the date and you don’t set the weekdays the timewindow is cleared for the keycode.

Best regards,
Tom

5

At least the allowedFromDate has to be set to time restrict an authorization.

If you are reffering to Nuki Web: User data is only synced to the Nuki Web once per day (bc authorizations are always directly stored on the Smart Lock and not on our servers), so if you created a user and later changed the rights for it that would explain this. (But you should see the changes today.)

Some more detailed examples on how to set different restrictions can be found in this topic:

And, yes, curl on Windows is tricky. I use the Ubuntu bash (https://www.microsoft.com/en-us/p/ubuntu/9nblggh4msv6?activetab=pivot:overviewtab) on Windows. E.g. Lynx should also work fine for testing, if you want to use a (minimal) browser.

6

Hi! Is there any way to get the id upon authorization creation?
My process is, given a specific name, I need to check if an authorization exists with that name, if not create it, then get his id (looping through list and search for the name) and then updating stuff (dates, …) on my authorization.
The problem is that the freshly created authorization doesn’t appear directly in the list (there is a delay) and my process crash as it can’t find the newly created authorization.
Thanks

7

I’m sorry, but there is no way to get it directly at the moment. And yes, there can be a delay as authorization are created directly at the Smart Lock and then need to be synched back to be shown in the Web API.

8

Ok… so I managed to either create or update with additional api calls. It’s working.
My issue now is with the timezone and dates.
When I send this “allowedFromDate”:“2020-06-01T12:00Z” (it is the format provided in you examples),
In the Nuki Web App it displays as “14h” instead of the “12h” submitted.
So I don’t know if I have the right time or not. I expect to work with “the smartlock time”, so if I send “12:00” as time, it will be “12:00” smartlock’s time.
Can you please clarify ?
Thanks

9

We use UTC on Smart Lock time, but always show local time to end users, so you need to consider this.

For Smart Lock 1.0 we used a Timezone offset (set Smartlock.Config / timezoneOffset)
For Smart Lock 2.0 you can find the timezone set at Smartlock.Config / timezoneId (IDs in the documentation)

10

Would it be possible to program the Keypad via the HTTP Bridge API’s? If that’s possible, I’m going to guess that getting callback notifications from the keypad is also going to get easier.

11

No, this is not possible at the moment as it need admin rights to change permissions, which the Bridge does not have.

12

Okay I understand. Would it atleast be possible to get notified about key codes usage through a bridge callback? That way while we can’t program codes, atleast we can use then keypad with third party apps which manage their own keycodes and currently control the locks directly through the bridge. Would you still need admin rights to get a callback notification of which code was entered and let the bridge authenticated apps handle the rest?
Plus it opens up a lot of new ways to use then keypad beyond use using it with locks (example to control security systems, garage doors and lots more).

13

Hi Stephan

I tried to create a new PIN on the swagger API page and used the very same example as in the first post, but I when I fired the callout I got back the following response:

{
“detailMessage”: “The supplied value ‘13’ for parameter ‘type’ is not valid”,
“stackTrace”: [],
“suppressedExceptions”: []
}

I can also see on swagger that for type 13 means keypad ->
“type (integer, optional): The optional type of the auth 0 … app (default), 2 … fob, 13 … keypad”

Can you please help why this happening.

Regards
Viktor Pári

14

Is a Keypad paired to the Smart Lock for which you want to create the code? If not, this would cause this error.

15

Hi Stephan,
Thank you for the fast response!
I have the keypad paired. The keypad works with the lock I tried it, but just like creating a PIN does not with from swagger I also unable to retrieve the two already created PIN. I created those with the Nuki mobile app.
Can you advice what step I am missing in order to pair the keypad?
Many Thx!
Viktor

1 Like
16

@viktor.pari One thing you could check for me: If you GET /smartlock do you see keypadPaired = yes?

And btw. if you check, serverState should be 0 if everything is online.

As you already got an API key to test, Bridge/Nuki Web setup seem to have worked fine for you. I just want to rule out that the state of a later paired Keypad is not synched correctly.

If this happened you can also try to force sync via
PUT /smartlock/{smartlockId}/sync

2 Likes
17

Many thx Stephan!
The keypad was not paired, but force sync solved the issue. I already managed to create a PIN too.

Thank you again!
Have a nice weekend!
Viktor Pári

1 Like
18

When I create a code for the nuki keypad for a guest, I thought there will be an automatically email sent to the guest with the code. Or was this just via the Airbnb integration? And also just when I invite without a keypad code?
So I have to write an own email, right? Or is there just a problem actually?

19

When you create a Keypad code via Web API you can assign an accountUser but we will still not send out an e-mail (as we do for inivtes which you would still have to redeem in the Nuki App). We are sending out a (combinded) e-mail for invites and/or keypad codes via the Airbnb interface.
But in your case you would have to send it out yourself, yes.

20

Is it possible to set time window when creating the key?
I do send it as put data in this format: 2020-03-19T16:00:00.000Z, but when looking on the nuki web app, the pin shows today’s date and unlimited end

The goal is to set the key from the begin at 16:00 to end day 16:00 is possible when creating the pin or do I need to edit the pin afterwards and add the values?