---
title: "Get Lock Dynamic PIN"
method: POST
path: "/get_lock_dynamic_pin"
tags: ["Locks"]
---

# Get Lock Dynamic PIN

`POST /get_lock_dynamic_pin`

## Request

- Base URL: `https://api.developer.atomberg-iot.com/v2`
- URL: `https://api.developer.atomberg-iot.com/v2/get_lock_dynamic_pin`
- Auth: API key in header `x-api-key` and HTTP bearer

Creates a temporary guest PIN for a smart lock.

PINs work differently on each lock, and each lock needs different inputs:

| Lock | Series | Send | PIN | Usable for |
| --- | --- | --- | --- | --- |
| Cypheo Elite | G1 | `device_id` only | 10 digits | about 15 minutes |
| Azhero Smart Door Lock / SL1 | smart_lock_black | `device_id`, `start_time`, `end_time` | 6 digits | the time window you asked for |

## How the PIN works on each lock

**For G1 Cypheo Elite, the PIN comes from the clock.** It is based on the minute it was created. The lock works out the same PIN from its own clock and checks that they match. Nothing is sent to the lock or stored, so the lock does not need to be online. The PIN works for about 15 minutes and you cannot choose the time window. `start_time` and `end_time` are not needed and are ignored if sent.

**For the Azhero Smart Door Lock / SL1, the PIN is stored on the lock** for the time window you choose, so you must send `start_time` and `end_time`. If a guest PIN already on the lock covers your time window, that PIN is returned and no new one is created.

## Request

| Where | Name | Required | Value |
| --- | --- | --- | --- |
| Header | `x-api-key` | Yes | Your developer API key. |
| Header | `Authorization` | Yes | `Bearer <access_token>` |
| Header | `Content-Type` | Yes | `application/json` |
| Body | `device_id` | Yes | A lock on your account. |
| Body | `start_time` | Only for Azhero / SL1 | When the PIN starts working. UTC epoch **seconds**. Ignored by G1. |
| Body | `end_time` | Only for Azhero / SL1 | When the PIN stops working. UTC epoch **seconds**, later than `start_time`. Ignored by G1. |

If the `device_id` is not a lock, you get a `400` error that says what kind of device it is.

Both time fields are epoch **seconds**, not milliseconds. If you send milliseconds, the time window will be far too long.

## Response

```json
{
  "status": "Success",
  "message": {
    "data": {
      "otp": "482913",
      "validStartTime": 1767304800,
      "validEndTime": 1767305039
    }
  }
}
```

| Field | Type | Meaning |
| --- | --- | --- |
| `message.data.otp` | string | The PIN to give your guest. It is a string, not a number, because it can start with 0. |
| `message.data.validStartTime` | integer | When it starts working, epoch seconds. |
| `message.data.validEndTime` | integer | When it stops working, epoch seconds. |

**Always use the time window from the response.** For G1, the time window is short and set by the lock. For Azhero / SL1, it can be *wider* than you asked for, because an existing guest PIN that covers your time window is reused.

A PIN **cannot be cancelled** before it expires, so ask for short time windows.

When an Azhero Smart Door Lock / SL1 creates a new PIN, the API returns the reply from the lock's own platform without changing it. Its format can differ from the example above.

## Request body

- object
  - `device_id` string, required: A lock on your account, from 'Get List of Devices'.
  - `start_time` integer: Required only for the Azhero Smart Door Lock / SL1 (series `smart_lock_black`). When the PIN starts working, in UTC epoch seconds. Ignored by G1.
  - `end_time` integer: Required only for the Azhero Smart Door Lock / SL1 (series `smart_lock_black`). When the PIN stops working, in UTC epoch seconds, later than `start_time`. Ignored by G1.

## Response `200`

OK

- DynamicPinResponse
  - `status` string: `Success` on a 2xx, `Error` otherwise.
  - `message` object: The response data. Each endpoint has its own format.
    - `data` DynamicPin
      - `otp` string: The PIN to give your guest.
      - `validStartTime` integer: When the PIN starts working, in epoch seconds.
      - `validEndTime` integer: When the PIN stops working, in epoch seconds.

## Other responses

- `400`: The request is not valid, or the command is not supported by that device. The message names the wrong key and lists what the device accepts.
- `401`: The API key or token is missing, malformed or expired, or it is the wrong kind of token.
- `403`: Developer Mode is not enabled for this account, or the user does not exist. You also get a 403 when the URL path or HTTP method is wrong.
- `404`: The device is not on your account, or it has not reported any state yet.
- `429`: You have used up your API key's daily quota, or gone over the per-second limit. The daily quota resets at 00:00 UTC.
- `500`: Something failed on our side. Your request was fine. Try again after a short wait.
- `501`: This API does not support the device's series. The message lists the supported series.
- `502`: The Atomberg platform behind this API could not deliver the command or create the PIN. Try again after a short wait.
- `504`: The request took longer than 29 seconds. A command may still have reached the device, so check 'Get Device State' before you send it again.

## Changes

- **2026-10-06** `30e1ea1bdb73`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/atomberg-iot/apis/atomberg-home-public-apis/changes/get_lock_dynamic_pin/post.md)

---

[API](https://skmtc.dev/atomberg-iot/apis/atomberg-home-public-apis.md) - [All operations](https://skmtc.dev/atomberg-iot/apis/atomberg-home-public-apis/llms.txt) - [OpenAPI document](https://skmtc.dev/atomberg-iot/apis/atomberg-home-public-apis/revisions/35290532bede?raw)
