Recurring Keys
Does your integration or service require recurrent access to Locks over an extended period? It might be a good idea to limit when and for how long each Key you generate will be active. This will allow you to offer your clients traceability and logging of your activities on their premises.
The Unloc platform has this covered through the recurrence characteristic of the Key creation endpoint for its APIs.
It's usage only involves the addition of a recurrence
property to the Key creation request body. The recurrence object must then specify which days and time periods the Key should be active for.
Depending on whether you’re using the Integrator API or the Service Provider API, you’d need to add extra data to the request body. Check out the API Reference for each case:
The recurrence
object
recurrence
objectThe recurrence object should contain a property (or object key) for each day of the week the Key should be active. Those days of the week will, at the same time, define a start and end time split by hours and minutes. The start and end times are in the same timezone as the Lock.
{
// ... the rest of your request body
"recurrence": {
"**day_of_the_week**": {
"startHour": 14,
"startMinute": 45,
"endHour": 16,
"endMinute": 30
}
}
}
Fields
Field | Description |
---|---|
day_of_the_week | It is a direct child of the recurrence object.It should be the first three letters of the name of a day of the week in English in lowercase: "sun", "mon", "tue", "wed", "thu", "fri", "sat", or "sun". |
startHour | An integer ranging from 0 to 24 |
startMinute | An integer ranging from 0 to 59 |
endHour | An integer ranging from 0 to 24 |
endMinute | An integer ranging from 0 to 59 |
Examples
Picture an elevator maintenance company that needs to send a technician to perform weekly inspections. Let’s say that the contract between the elevator maintenance company and the building will last for a year, and the inspections are to be performed on Saturdays between 14:45 and 16:30. A recurrent key request body for that scenario will look like this:
{
// ...
"start": "2021-08-01T12:00:00.000Z",
"end": "2022-08-01T00:00:00.000Z",
"recurrence": {
"sat": {
"startHour": 14,
"startMinute": 45,
"endHour": 16,
"endMinute": 30
}
}
}
How about a company that supplies fresh berries to a restaurant during the season? They might deliver them every day right to the chef’s table early in the morning, well... except on Mondays and Tuesdays when the chef wakes up a bit later and opens the kitchen at 8 AM instead of the usual 6AM schedule:
{
// ...
"start": "2022-04-11T6:00:00.000Z",
"end": "2022-07-301T12:00:00.000Z",
"recurrence": {
"sun": {
"startHour": 6,
"startMinute": 0,
"endHour": 10,
"endMinute": 30
},
"mon": {
"startHour": 8,
"startMinute": 0,
"endHour": 11,
"endMinute": 0
},
"tue": {
"startHour": 8,
"startMinute": 0,
"endHour": 11,
"endMinute": 0
},
"wed": {
"startHour": 6,
"startMinute": 0,
"endHour": 10,
"endMinute": 30
},
"thu": {
"startHour": 6,
"startMinute": 0,
"endHour": 10,
"endMinute": 30
},
"fri": {
"startHour": 6,
"startMinute": 0,
"endHour": 10,
"endMinute": 30
},
"sat": {
"startHour": 6,
"startMinute": 0,
"endHour": 10,
"endMinute": 30
}
}
}
Time frame
When creating a recurrence object, keep in mind that there should be at least one minute difference between the start and end times (realistically, it should live for longer). Failing to do so will result in an error response from the API. For instance:
{
"error": "validationFailed",
"errorDescription": "fri: start time must be before end time"
}
Midnight
When pointing the endHour
to midnight, the value 24
should be used.
The value0
is considered the first hour of a day.
Mixing these values up will result in the above mentioned error response.
Updated about 1 year ago
Want to know more about creating keys?