HTTP API lockState and the unlatched state

Hi there,

I realise this is a similar question to what was asked before but I want to know if the HTTP API (bridge API) will show the proper door state in the near future. Currently it never shows “unlatched”.

I realise the Web API does give this state, but I want to be secure and only work with a local Home Assistant integration. I don’t believe it is right to require customers to use the Web API to get a state such as “unlatched”, so perhaps you already plan to release this state for the HTTP API too?


Hello, can you share your insights please?

The problem is, that the current Callbacks are only sent after a lock action is finished and reflect the final state.
This is the answer that the NUKI team replied to many questions about this in the forum.

I opened a feature request because of this, but I’m not sure anymore if the request in it’s current state is a good idea:

I’m not sure if the callback system needs a bigger rework to get this done the right way.
The current system (only one callback type which was thought as representing the current state of the lock instead of sending “events”) might be the reason for many shortcomings of the HTTP API.

If we would have an event driven system for the callback this would make things a lot easier for the NUKI devs.
There could be different event types, and based on the event type it would be possible to use different JSON structures.
This would allow them to add new event types without breaking existing implementations on the customer side.
At the moment we have one structure for all callbacks, regardless what happened. It’s more or less the same you get if you manually poll the status, just sent automatically to you.

I think this is the problem why we still don’t have callback calls for the Opener when someone rings at the door.
And it’s also the reason why we don’t get real events for the lock like “Door was opened” or even better “Door was opened by Person X” Where Person X, can be a Fob ID, “Unknown” or the user in case of a smartphone, like we already see it in the log of the app or as the website lists.

This isn’t easy to implement now, if you have to stay compatible with your current implementation.

By the way, most of this stuff is already implemented through IFTTT, which also leads me to the assumption,
that these features would already be in the HTTP API if it would be easy to add…

I took the chance to improve my feature request:

Thanks for your elaborate answer Tobias. I did see that other thread talking about callbacks, but I decided to make this new thread because I want the state to be shown when querying the API itself (so, not related to callbacks).

Lockstate, as defined here: has the state “unlatched” as one of the possible states. The response from the API request /lockState however never responds with “unlatched”. It only ever responds with “locked” or “unlocked” when the door is open (=unlatched).

Maybe the problem is that the ‘locked/unlocked’ and ‘unlatched’ states can in fact overlap? A Nuki can be in locked state, with the door unlatched. Also, a Nuki can be in the unlocked state, with the door being unlatched.

In that case, I would want the “unlatched” state to be dominant in the API response. Whether the door is locked or unlocked, I would want the API to reply with “unlatched”.

As far as I understand, “unlatched” means the state when the latch is pulled.
So you can change from “locked” to “unlatched” (with a “unlocked” state in between) but your lock can’t be in the locked and unlatched position at the same time.

Haven’t checked yet what happens if you call /lockState right in the moment where the lock is in “unlatched” position, as this position is only active for about 2-3 seconds before the latch will be released.

Maybe you mix up unlatched with open door (which can only be determinated with a V2 Smartlock using the door sensor)?
If so, my feature request also includes adding the door sensor to the API. :stuck_out_tongue:

Yes, you can get the state “unlatched” via /lockState call (you can e.g. test it by setting an unlatch time of 30 sec).

Currently state changes still only trigger after finished lock actions (as @Thyraz pointed out correctly before).


I’ve been using the HTTP callback interface for several months now and I’m very dissatisfied with that function.
I use the interface together with my smart home system and I want to be informed on every lock state change. But this is very unrelaible and I only get a very few state changes via callback.
Why do you send only a few of the 11 possible lock states? What I always get is lock state 1 (locked), 3 (unlocked) and 2 (unlocking). What I get very, very rarely is lock state 7 (unlatching). All other lock states I don’t get via HTTP callback. That’s very annoying. Yesterday I had a blocked motor. This was logged in the protocol in the NUKI app. But I didn’t receive that lock state via HTTP callback.

Could you please improve the callback interface and send all lock states immediately? I’d expect at least the following states otherwise the callback function is quite useless in my opinion:

  • 0 - uncalibrated
  • 1 - locked
  • 3 - unlocked
  • 5 - unlatched
  • 254 - motor blocked
  • 255 - undefined

I don’t expect a negative impact on battery life if you send all lock states. Perhaps you can implement an option that the user can configure which lock state changes should be immediately sent.

This is a current functional limitation as only the last known state change is triggered by the callback and so the unlatch state is most likely replaced by the following state “too fast” in your cases.

Please add a feature request and start collecting votes for this (as well as for your wish to be informed about all lock state changes - and not only the last known). If there is enough interest in such an expansion we can look at the feasibility in detail.