Skip to main content
Some devices only accept access codes whose time frame—its duration and, sometimes, its time of day or calendar dates—falls within limits that the lock or its manufacturer enforces. When creating a time-bound access code, get the device and review two device.properties so that you can build a valid time frame before you call /access_codes/create, rather than discovering the constraint from an error.
  • device.properties.offline_time_frame_options applies to offline access codes.
  • device.properties.online_time_frame_options applies to online access codes.
Each property is an array of options. An option is one self-contained way to make a code: a duration band plus any time-of-day and date rules that apply within it. To create a valid code, pick one option and satisfy all of its rules. These properties are split by code type because you always know which kind of code you are creating, so you read the matching property directly. Splitting them also lets a provider express different limits per code type—for example, a device that allows a longer duration for online codes than for offline codes.
Read these options from the device at request time and build your time frame from the values you find—do not hardcode limits per manufacturer. Providers gain support and adjust their bounds over time, so a device’s current time_frame_options are always the source of truth.
When a property is undefined, any time frame works for that code type on that device—there are no time-frame limits to observe. A device may define one property and leave the other undefined. For example, a lock that only programs online codes exposes online_time_frame_options and leaves offline_time_frame_options unset. Standard online locks and thermostats leave both undefined.

​
The Time Frame Option Object

Every property except display_name is optional, and the absence of a rule means unrestricted on that axis. An option with only min_duration and max_duration constrains duration and nothing else—any time of day, any date. An option with only max_duration means “any time frame up to that length.”
start_date_recurrence_rule and end_date_recurrence_rule are part of the schema for forward compatibility, but no provider populates them yet. Today, every option either leaves the date axis unrestricted or fixes times of day through time_pairs.

​
The Time Pair Object

A time pair is atomic: you pick one whole pairing, and you cannot mix a start_time from one pair with an end_time from another.

​
Choosing an Option

  1. Filter by duration. Compute your requested duration and keep the options whose [min_duration, max_duration] band contains it.
  2. Disambiguate. How you land on a single option depends on whether the options’ duration ranges overlap:
    • Non-overlapping ranges (the common case): The requested duration falls into exactly one option, so the duration alone selects it. You just enter dates.
    • Overlapping ranges: Duration cannot disambiguate, so the options are genuine alternatives that you choose between by display_name.
  3. Satisfy that option’s rules. Honor its time-of-day rule (matching_start_end_time or one time_pairs entry) and any start_date_recurrence_rule or end_date_recurrence_rule, interpreting times and dates in time_zone.
You do not need a flag to tell these cases apart—it falls out of the ranges. If two options can both accept the requested duration, present them as a choice; otherwise, route by duration.
When start_date_recurrence_rule or end_date_recurrence_rule is present, max_duration caps the range, but the only valid dates are recurrence dates within that cap. Offer only recurrence dates within the duration bound, not every date up to the cap.

​
Examples

​
Duration-Only Option

For example, an igloohome algoPIN hourly code accepts any time of day, from one hour to 28 days:

​
Matching Start and End Time

For example, an igloohome algoPIN daily code covers 29 to 367 days, and the check-in and check-out must be at the same time of day:

​
Fixed Time Pairs

For example, a Dormakaba Oracode offline code offers the fixed check-in/check-out pairings defined for the door, up to 31 days, in the lock’s local time zone:

​
Multiple Options on One Property

For example, an igloohome algoPIN device exposes two duration-matched offline options. The ranges don’t overlap, so Seam selects the option by the requested duration—you never pick. Its online (bridge) codes are unconstrained, so online_time_frame_options is undefined.
As another example, a KeyInCode SmartPIN device programs online codes only and exposes two duration-matched online options: short-term codes are unrestricted on time of day, while long-term codes are fixed to an 8 AM check-in and 8 PM check-out in the lock’s location time zone. Its offline_time_frame_options is undefined.