Access Codes

Key Codes to be programmed on a door lock.

Access Codes

The Access Code object

An Ongoing Access Code will be active until it has been removed from the Device. Be sure to leave both the starts_at and ends_at fields empty to specify an ongoing Access Code.

A Time Bound Access Code will be programmed at the **starts_at**time, and removed at the ends_at time.

Access Code Names

Note that the name provided on Seam is used to identify the code on Seam, and is not necessarily the name that will appear on the lock provider's app, or on the device. This is because lock providers may have constraints on names such as length, uniqueness or characters that can be used. In addition, some lock providers may break down names into components such as first_name and last_name.

In order to provide a consistent experience, Seam will identify the code on Seam by its name but may modify the name that appears on the lock provider's app, or on the device. For example, Seam may add additional characters or truncate the name in order to meet provider constraints.

In order to help end users identify codes set by Seam, Seam provides the name exactly as it appears on the lock provider's app, or on the device as a separate property called appearance. This is an object with a name property, and optionally, first_name and last_name properties (for providers that break down a name into components).

External Modification

Seam will attempt to keep the access code on the device in sync with the declared state of the access code on Seam. For example, the start time and end time of the access code will be set to match the declared state of the access code on Seam. Any updates to the access code timings on Seam will be reflected on the device. In general, if the access code is modified external to Seam (through the lock provider's app for example), Seam will attempt to re-set the access code on the device to match the declared state of the access code on Seam. This also applies if the access code is removed from the device. Seam will attempt to re-set the access code on the device until the declared ending time of the access code has passed.

When external modifications are detected, Seam will send an access_code.modified_external_to_seam event and add a code_modified_external_to_seam error on the access code.

This behavior can sometimes be surprising to end users, so we recommend that you inform your users that Seam will attempt to re-set access codes on the device if they are modified or removed externally. If you would like to disable this behavior, you can set the allow_external_modification flag to true when an access code. When this flag is set to true, Seam will set code_modified_external_to_seam as a warning on the code instead of an error.

Access Code Error Types

Errors are returned in a list:

"errors": [
  {
    "is_access_code_error": true,
    "error_code": "device_disconnected",
    "message": "Device Disconnected, you may need to reconnect the device.",
    "created_at": "2023-06-27T22:50:19.440Z
  }
]

Generic Errors

Seam recommends adding error handling logic to you application for each generic error below. Seam may add more generic errors in the future, so your application should include a fallback case if it encounters an unknown generic error code.

See our troubleshooting tips for access codes for our recommended responses to these error codes.

Specific Errors

When Seam is able to provide more specific information beyond one of the generic errors above, one or more errors from the list of specific errors may appear. This gives your application the option to display additional context or suggest provider specific resolutions.

If the device or connected account associated with an access code has an error, it will be attached to the access code alongside any other access code errors. Treat these errors as Specific Errors. See Device Error Types and Connected Account Error Types.

See our troubleshooting tips for access codes for our recommended responses to these error codes.

Access Code Warnings

An access code can have more than one error or warning.

Warnings are returned in a list:

"warnings": [
  {
    "warning_code": "delay_in_removing_from_device ",
    "message": "We expected the device to report that the access code has been removed but it still has not.",
    "created_at": "2023-06-27T22:50:19.440Z
  }
]

List of Methods

Last updated

Logo

Š Seam Labs, Inc. All rights reserved.