# AlgoPIN Codes

AlgoPIN generates valid PIN codes for a lock without WiFi, cellular, or remote access to the lock.

## How It Works

```mermaid
sequenceDiagram
  Note over Your Server, Our Server: iglooworks API
  Your Server->>Our Server: Request AlgoPIN
  Our Server-->>Your Server: AlgoPIN code
  Your Server->>Guest: AlgoPIN code
  Guest->>Lock: Enter AlgoPIN code
  Lock->>Lock: Unlock
```

## Types of AlgoPIN Codes

| Type | Validity | Variances | API |
| --- | --- | --- | --- |
| One-Time (OTP) | Single use | 10 | [Create a One-Time AlgoPIN](/works/api_access#create-a-one-time-algopin) |
| Permanent | No end date | 10 | [Create a Permanent AlgoPIN](/works/api_access#create-a-permanent-algopin) |
| Duration (Hourly) | 1 to 672 hours | 3 | [Create an Hourly AlgoPIN](/works/api_access#create-an-hourly-algopin) |
| Duration (Daily) | 29 to 367 days | 3 | [Create a Daily AlgoPIN](/works/api_access#create-a-daily-algopin) |
| Passage | 1 to 12 hours | 1 | [Create a Passage AlgoPIN](/works/api_access#create-a-passage-algopin) |

A Passage AlgoPIN unlocks the lock and keeps it unlocked for the chosen number of hours. Passage requires newer lock firmware.

## AlgoPIN Limitations

| Limitation | Explanation |
| --- | --- |
| AlgoPIN-supported devices only | The device has to support AlgoPIN. See [Supported Devices](/works/supported-devices). |
| Paired devices | Pair the device with the iglooworks app first. |
| 24-hour activation | AlgoPIN codes valid for more than 24 hours need activation on the lock. Use the PIN code on the lock within the first 24 hours of its validity. |
| 256 rule | You can't delete an AlgoPIN whose start date is more than 256 hours after its creation. |
| 199 rule | The lock's whitelist and blacklist hold at most 199 PIN codes in total (AlgoPIN and Bluetooth PIN codes). |
| PINs per duration | For one duration, you can generate only as many PINs as the type's [variances](#variance-multiple-algopin-codes-for-the-same-duration). |

## Variance: Multiple AlgoPIN Codes for the Same Duration

For a given duration, each variance returns a different PIN code. The Types table above lists the number of variances per type.

One-Time and Permanent support 10 variances on locks with newer firmware. Some older locks gain this with a firmware update; others support 5.

Example of hourly PIN codes for one lock, three variances each:

| Start time | End time | PIN codes (variance 1, 2, 3) | deviceId |
| --- | --- | --- | --- |
| 2PM | 3PM | 511093918, 945844647, 052368115 | IGB403fe3b9d |
| 2PM | 4PM | 633654730, 437755350, 337288611 | IGB403fe3b9d |
| 3PM | 5PM | 297248165, 196981787, 384522901 | IGB403fe3b9d |
| 3PM | 5PM | 948950871, 142404925, 817840781 | IGP114cde456 |

The following request returns a unique PIN code (e.g. `4642226`):

```bash
curl --request POST \
  --url https://api.igloohome.co/works/devices/IGP101abc123/algopin/onetime \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer abcdef' \
  --data '{
  "variance": 1,
  "startDate": "2022-01-01T00:00:00+08:00",
  "accessName": "Maintenance guy"
}'
```

Changing the variance returns a second unique PIN code (e.g. `1419472`) for the same duration:

```bash
curl --request POST \
  --url https://api.igloohome.co/works/devices/IGP101abc123/algopin/onetime \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer abcdef' \
  --data '{
  "variance": 2,
  "startDate": "2022-01-01T00:00:00+08:00",
  "accessName": "Maintenance guy 2"
}'
```