422 Error When Creating Type 13 Authorization via Web API (Keypad 2)

[Seunghyun_Kim]

Hi Nuki Developer Team,

I am trying to create a type: 13 authorization (Keypad PIN code) via the Nuki Web API (/smartlock/auth endpoint).

Here is a sample test I am sending:

{
  "smartlockId": 18298712180,
  "name": "PIN for hongpei17@gmail.com",
  "code": 719877,
  "type": 13,
  "allowedFromDate": "2025-04-26T14:45:00.000Z",
  "allowedUntilDate": "2025-04-26T16:00:00.000Z"
}

Important Details:

• The payload is valid JSON and matches the Web API documentation.
• My API token is valid (I can list locks and list current authorizations without any issues).
• The Smart Lock (ID: 18298712180) has a Keypad 2 paired and working (confirmed inside the Nuki app).
• The PIN format is a random 6-digit number, not reused.

Problem:
Every time I try to create this type: 13 authorization, I receive the following error from the Nuki Web API:

Error while creating PIN on Nuki Web API:
{
  code: 422,
  description: 'The server understands the content type of the request entity and the syntax of the request entity is correct but was unable to process the contained instructions',
  reasonPhrase: 'Unprocessable Entity'
}

This clearly shows that:

• The server accepts the content type and syntax (so no formatting issues).
• The server refuses to process the instructions in the payload itself (application-level rejection).

Questions:

1. Is it currently possible to create a new type: 13 (Keypad PIN) on a Keypad 2 device using the Nuki Web API?
2. If not, is this a known limitation that Keypad 2 PINs must be created via Bluetooth only?

I appreciate your help clarifying this.
We are building a system where users automatically receive temporary access PINs (for a practice room booking system), so understanding the full capability of the Nuki Web API vs Bluetooth API is critical for us.

[marc (Marc Mikolits)]

The name for a Keypad code must not exceed 20 chars.
Please try to use a shorter name and see if that fixes the issue.

[Seunghyun_Kim]

I saw your helpful reply about the 20-character name limit. I’ve updated my code to make sure the name field is now well under 20 characters.

However, I’m still getting the same 422 Unprocessable Entity error, even with the corrected payload.

{
  "smartlockId": 18298712180,
  "name": "hongpei17",
  "code": 719877,
  "type": 13,
  "allowedFromDate": "2025-04-26T14:45:00.000Z",
  "allowedUntilDate": "2025-04-26T16:00:00.000Z"
}

Error while creating PIN on Nuki Web API: {
nuki-app  |   code: 422,
nuki-app  |   description: 'The server understands the content type of the request entity and the syntax of the request entity is correct but was unable to process the contained instructions',
nuki-app  |   homeRef: '/',
nuki-app  |   reasonPhrase: 'Unprocessable Entity',
nuki-app  |   uri: 'http://www.webdav.org/specs/rfc2518.html#STATUS_422'
nuki-app  | }

[marc (Marc Mikolits)]

Unfortunately I’m not too familiar with our Web API but according to the Swagger example the smartlockId seems to be expected as a list.
So

"smartlockIds": [ id ]

instead of

"smartlockId": id

[Seunghyun_Kim]

Still getting 422 error with corrected smartlockIds field

I followed the advice provided earlier to use smartlockIds (array) instead of smartlockId (single value).

Here is my current request payload:

{
  "smartlockIds": [18298712180],
  "name": "hongpei17",
  "code": 643020,
  "type": 13,
  "allowedFromDate": "2025-04-28T14:45:00.000Z",
  "allowedUntilDate": "2025-04-28T16:00:00.000Z"
}

The request is sent to:

POST https://api.nuki.io/smartlock/auth

with a valid Bearer token and the correct Content-Type: application/json.

However, the server still returns the same 422 Unprocessable Entity error:

{
  "code": 422,
  "description": "The server understands the content type of the request entity and the syntax of the request entity is correct but was unable to process the contained instructions"
}

I mportant Details:

• The Smart Lock (ID: 18298712180) has a Keypad 2 paired and working.
• My token is working for other API endpoints (lock listing, authorization listing, etc).
• The "name" is within 20 characters.
• The "code" is a unique 6-digit number.
• The "allowedFromDate" and "allowedUntilDate" are in correct ISO 8601 format.

Questions:

1. Are there additional hidden requirements for creating a type: 13 authorization via Web API?
2. Is type: 13 fully supported for Keypad 2 devices when using the Web API, or only via Bluetooth API?
3. Could there be limitations with certain firmware versions or specific Smart Lock configurations?

Thank you for your support —
I just want to confirm the official possibility to create Keypad 2 PINs over Web API.

[marc (Marc Mikolits)]

In this case the code itself might cause the problem.
Out Keypad does not have a “0” digit therefore your code cannot be used.

But @andrew.oconnell will be able to better assist here

[Seunghyun_Kim]

Hi Marc,
Thank you very much for your quick response earlier — I really appreciate your support.

I carefully followed all previous advice:

• I updated my request to use "smartlockIds" (array) instead of "smartlockId".
• I ensured the "name" field is less than 20 characters.
• I ensured the "code" (PIN) does NOT contain the digit “0” — only digits 1–9.
• I am sending the correct "allowedFromDate" and "allowedUntilDate" in ISO 8601 format.
• The Smart Lock (ID: 18298712180) has a Keypad 2 paired and working.
• I am using a valid Bearer token and Content-Type: application/json.

Here is my current payload:

{
  "smartlockIds": [18298712180],
  "name": "hongpei17",
  "code": 325154,
  "type": 13,
  "allowedFromDate": "2025-04-28T14:45:00.000Z",
  "allowedUntilDate": "2025-04-28T16:00:00.000Z"
}

Endpoint:

POST https://api.nuki.io/smartlock/18298712180/auth

Response from Nuki Web API:

{
  "code": 422,
  "description": "The server understands the content type of the request entity and the syntax of the request entity is correct but was unable to process the contained instructions",
  "homeRef": "/",
  "reasonPhrase": "Unprocessable Entity",
  "uri": "http://www.webdav.org/specs/rfc2518.html#STATUS_422"
}

Important:

• The PIN (325154) is a unique 6-digit code containing only digits 1–9.
• The "name" is short (only 9 characters).
• The token works fine for other endpoints (lock listing, authorization listing).
• I am using proper Content-Type headers.

Additional Information:

You can also view my project code here if needed :

GitHub - HONGBAEKIM/nukipin

[andrew.oconnell]

Hi there,

If I understand correctly, you’re trying to create authorisations and not update them, correct? If so, please try a PUT request instead of a POST request.

Let me know if that resolves the issue

[Seunghyun_Kim]

This makes sense, now it is working!! Have a great day!