Recurrence

Recurrence lets you limit access to a given time frame. Recurrence is supported both when creating Keys and when creating Access Groups.

It's usage only involves the addition of a recurrence property when creating Keys or Access Groups. The recurrence object must then specify which days and time periods the Key should be active for.

The recurrence object

The recurrence object should contain a time span (or object key) for each period the Key should be active. Each property reference a day of the week and a start and end time split by hours and minutes. The start and end times are in the same timezone as the Lock.

{
  "recurrence": {
    timeSpans: [
     	{
      	"weekday": "mon",
      	"startHour": 14,
      	"startMinute": 45,
      	"endHour": 16,
      	"endMinute": 30
    	}
  	]
  }
}

❗️

The platform currently only support one recurrence period per day.

Fields

Examples for Keys with Recurrence

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": {
    "timespans": [{
      "weekday": "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": {
    "timeSpans": [
      {
        "weekday": "mon",
        "startHour": 8,
        "startMinute": 0,
        "endHour": 11,
        "endMinute": 0
      },
      {
        "weekday": "tue",
        "startHour": 8,
        "startMinute": 0,
        "endHour": 11,
        "endMinute": 0
      },
      {
        "weekday": "wed",
        "startHour": 6,
        "startMinute": 0,
        "endHour": 10,
        "endMinute": 30
      },
      {
        "weekday": "thu",
        "startHour": 6,
        "startMinute": 0,
        "endHour": 10,
        "endMinute": 30
      },
      {
        "weekday": "fri",
        "startHour": 6,
        "startMinute": 0,
        "endHour": 10,
        "endMinute": 30
      },
      {
        "weekday": "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.

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.