How to manage PIN list of the lock
If you have a lock paired with a keypad and your lock is also paired with a bridge, you can manage pins using API. In this tutorial we will walk through the process of listing, creating, updating, and deleting pins for the lock device.
Get current pin list
If you want to get the current pin list for the lock, you will need deviceId and use Get all pins endpoint.
Sample request for lock with id = 123
curl -X GET "https://api.tedee.com/api/v37/my/lock/123/pin" -H "accept: application/json" -H "Authorization: Bearer <<access token>>"
This endpoint will return all pins for the given lock.
Sample response
HTTP status code: 200
{
"result": {
"listVersion": 2,
"pins": [
{
"id": 1,
"alias": "test pin 1"
},
{
"id": 2,
"alias": "test pin 2"
}
]
},
"success": true,
"errorMessages": [],
"statusCode": 200
}
Using the listVersion parameter
Every response includes a listVersion number. This version is incremented after each change to the pin list
(create, update, or delete). You can use it to avoid fetching the full list unnecessarily:
On the first call, omit
listVersion— you will receive the full list together with the currentlistVersion.Store the returned
listVersionvalue on your side.On subsequent calls, pass the stored value as
?listVersion=<value>.If the list has not changed since your last fetch, the API returns
304 Not Modified— no data transfer needed.If the list has changed, the API returns
200 OKwith the full updated list and a newlistVersionto store.
Always update your stored listVersion to the value returned in the latest 200 OK response.
Sample request passing the last known list version for lock with id = 123
curl -X GET "https://api.tedee.com/api/v37/my/lock/123/pin?listVersion=2" -H "accept: application/json" -H "Authorization: Bearer <<access token>>"
Sample response when the provided version of the list is up-to-date
HTTP status code: 304
{
"success": false,
"errorMessages": [
"List version is up to date."
],
"statusCode": 304
}
Sample response when a newer version of the list is available
HTTP status code: 200
{
"result": {
"listVersion": 3,
"pins": [
{
"id": 1,
"alias": "test pin 1"
},
{
"id": 2,
"alias": "test pin 2"
}
]
},
"success": true,
"errorMessages": [],
"statusCode": 200
}
Get pin details
If you want to get details of a selected pin, you will need deviceId along with pinId and use Get single pin endpoint.
Sample request for lock with id = 123 and pin with id = 2
curl -X GET "https://api.tedee.com/api/v37/my/lock/123/pin/2" -H "accept: application/json" -H "Authorization: Bearer <<access token>>"
This endpoint will return pin details.
Sample response
HTTP status code: 200
{
"result": {
"id": 2,
"alias": "test pin 2",
"pin": "192837",
"startDate": "2021-10-01T00:00:00.000Z",
"endDate": "2021-12-31T00:00:00.000Z",
"dayStartTime": "2021-10-01T10:00:00.000Z",
"dayEndTime": "2021-10-01T18:00:00.000Z",
"weekDays": 1
},
"success": true,
"errorMessages": [],
"statusCode": 200
}
Create a new pin
If you want to add a new pin for the given lock, you will need deviceId and use Create pin endpoint.
Note
The pin value must meet the following requirements:
pin cannot be null, empty, or whitespace
pin length must be between 5 and 8 digits
pin can contain only numeric characters (0–9)
pin must contain at least 3 different digits
pin cannot be a strictly ascending or descending sequence (e.g.
12345or54321)
Sample request for lock with id = 123
curl -X POST "https://api.tedee.com/api/v37/my/lock/123/pin" -H "accept: application/json" -H "Content-Type: application/json-patch+json" -H "Authorization: Bearer <<access token>>" -d "<<body>>"
This endpoint will return Id of the created pin.
Create a pin with permanent access to the lock
If you want to have a pin with permanent access to the lock, you only need to send pin alias and pin value:
Body:
{
"alias": "test pin 3",
"pin": "918273"
}
Create a pin with time restricted access to the lock
If you want to restrict pin access to the lock you can send fields “startDate” or “endDate”, it will mark the period when pin will be active. You can also restrict access to specific hours of the day by sending “dayStartTime” and “dayEndTime”. You can further customize this by selecting days. To send it proper way you need to use Week days enum.
In this case the created pin will be active from 1 October to 31 December:
Body:
{
"alias": "test pin 3",
"pin": "918273",
"startDate": "2021-10-01T00:00:00.000Z",
"endDate": "2021-12-31T00:00:00.000Z",
"dayStartTime": null,
"dayEndTime": null,
"weekDays": null
}
In this case the created pin will be active from 1 October to 31 December, and also will have access only on friday and saturday between 10:00 and 18:00:
Body:
{
"alias": "test pin 3",
"pin": "918273",
"startDate": "2021-10-01T00:00:00.000Z",
"endDate": "2021-12-31T00:00:00.000Z",
"dayStartTime": "2021-10-01T10:00:00.000Z",
"dayEndTime": "2021-12-31T18:00:00.000Z",
"weekDays": 48
}
In this case the created pin will be active only from monday to friday between 8:00 and 16:00:
Body:
{
"alias": "test pin 3",
"pin": "918273",
"startDate": null,
"endDate": null,
"dayStartTime": "2021-10-01T08:00:00.000Z",
"dayEndTime": "2021-10-01T16:00:00.000Z",
"weekDays": 31
}
Update selected pin
If you want to update the selected pin for the given lock, you will need deviceId and pinId. Before making any changes you should read the pin details to have complete information about the pin. To do that use Get single pin endpoint. Once you have all, you can send the updated information to the endpoint Update pin to update the pin.
Note
The pin value must meet the following requirements:
pin cannot be null, empty, or whitespace
pin length must be between 5 and 8 digits
pin can contain only numeric characters (0–9)
pin must contain at least 3 different digits
pin cannot be a strictly ascending or descending sequence (e.g.
12345or54321)
Sample request for lock with id = 123 and pin with id = 2
curl -X PUT "https://api.tedee.com/api/v37/my/lock/123/pin/2" -H "accept: application/json" -H "Content-Type: application/json-patch+json" -H "Authorization: Bearer <<access token>>" -d "<<body>>"
Body:
{
"alias": "new test pin 2",
"pin": "827364",
"startDate": "2021-10-01T00:00:00.000Z",
"endDate": "2021-12-31T00:00:00.000Z",
"dayStartTime": "2021-10-01T10:00:00.000Z",
"dayEndTime": "2021-10-01T18:00:00.000Z",
"weekDays": 1
}
Delete pin
If you want to delete selected pin for the given lock, you will need deviceId along with pinId and use Delete pin endpoint.
Note
Pins created with an endDate are automatically removed from the system once they expire.
Manual deletion is only necessary when you want to revoke a pin before its expiration date, or when removing a permanent pin.
Sample request for lock with id = 123 and pin with id = 2
curl -X DELETE "https://api.tedee.com/api/v37/my/lock/123/pin/2" -H "accept: application/json" -H "Authorization: Bearer <<access token>>"