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

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 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"...

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.


Did this page help you?