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:

• For the Integrator API
• Service Provider API

The recurrence object

The 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

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.