diff --git a/docs/api-clients/access-codes/README.md b/docs/api-clients/access-codes/README.md index d4f7c4d6..2ca7c963 100644 --- a/docs/api-clients/access-codes/README.md +++ b/docs/api-clients/access-codes/README.md @@ -1,14 +1,14 @@ --- -description: Key Codes to be programmed on a door lock. +description: Key codes to be programmed on a door lock --- # Access Codes -## Access Codes +### `access_code` Properties -### The Access Code object +The `access_code` object has the following properties: -
access_code_idString (UUID)Unique identifier for the access code.
device_idString (UUID)Unique identifier for the device associated with the access code.
codeStringCode used for access. Typically, a numeric or alphanumeric string.
nameStringName of the access code. Enables administrators and users to identify the access code easily, especially when there are numerous access codes.
common_code_keystringUnique identifier for a group of access codes that share the same code.
appearanceObjectName as it appears on the lock provider app or on the device. This is an object with a name property, and first_name and last_name properties if the provider breaks down names into components.
statusString

Current status of the access code within the operational lifecycle. Values are: unset: Indicates a deactivated or unused state, either before activation or after deliberate deactivation.


setting: A transitional phase that indicates that the code is being configured or activated.


set: Indicates that the code is active and operational.


removing: Indicates a transitional period in which the code is being deleted or made inactive.

unknown: Indicates an indeterminate state, due to reasons such as system errors or incomplete data, that highlights a potential need for system review or troubleshooting.

is_scheduled_on_deviceBooleanIndicates whether the code is set on the device according to a preconfigured schedule.
is_managedBooleanIndicates whether Seam manages the access code.
typeEnum

Nature of the access code. Values are:

ongoing: Access codes that are active continuously until deactivated manually.

time_bound: Access codes that have a specific duration.

is_backup_access_code_availableBooleanIndicates whether a backup access code is available for use if the primary access code is lost or compromised.
is_backupBooleanIndicates whether the access code is a backup access code.
pulled_backup_access_code_idString (UUID)Identifier of the pulled backup access code. Used to associate the pulled backup access code with the original access code.
is_waiting_for_code_assignmentBooleanIndicates whether the access code is waiting for a code assignment.
is_external_modification_allowedBooleanIndicates whether changes to the access code from external sources are permitted.
is_one_time_useBooleanIndicates whether the access code can only be used once. If true, the code becomes invalid after the first use.
is_offline_access_codeBooleanIndicates whether the access code is intended for use in offline scenarios. If true, this code can be created on a device without a network connection.
starts_atDatetime (ISO 8601)Date and time at which the time-bound access code becomes active (only relevant for time_bound codes).
ends_atDatetime (ISO 8601)Date and time after which the time-bound access code becomes inactive (only relevant for time_bound codes).
created_atDatetime (ISO 8601)Date and time at which the access code was created.
errorsSee Access Code Error Types.

Collection of errors associated with the access code, structured in a dictionary format.

A unique error_code keys each error. Each error entry is an object containing two fields: message and created_at.

message is a string that describes the error.

created_at is a date that indicates when the error was generated.

This structure enables detailed tracking and timely response to critical issues.

warningsSee Access Code Warning Types.

Collection of warnings associated with the access code, structured in a dictionary format.

A unique warning_code keys each warning. Each warning entry is an object containing two fields: message and created_at.

message is a string that describes the warning.

created_at is a date that indicates when the warning was generated.

This structure enables detailed tracking and timely response to potential issues that are not critical but that may require attention.

+
PropertyTypeDescription
access_code_idString (UUID)Unique identifier for the access code.
device_idString (UUID)Unique identifier for the device associated with the access code.
codeStringCode used for access. Typically, a numeric or alphanumeric string.
nameStringName of the access code. Enables administrators and users to identify the access code easily, especially when there are numerous access codes.
common_code_keyStringUnique identifier for a group of access codes that share the same code.
appearanceObjectName as it appears on the lock provider app or on the device. This is an object with a name property, and first_name and last_name properties if the provider breaks down names into components.
statusString

Current status of the access code within the operational lifecycle. Values are: unset: Indicates a deactivated or unused state, either before activation or after deliberate deactivation.


setting: A transitional phase that indicates that the code is being configured or activated.


set: Indicates that the code is active and operational.


removing: Indicates a transitional period in which the code is being deleted or made inactive.

unknown: Indicates an indeterminate state, due to reasons such as system errors or incomplete data, that highlights a potential need for system review or troubleshooting.

is_scheduled_on_deviceBooleanIndicates whether the code is set on the device according to a preconfigured schedule.
is_managedBooleanIndicates whether Seam manages the access code.
typeEnum

Nature of the access code. Values are:

ongoing: Access codes that are active continuously until deactivated manually.

time_bound: Access codes that have a specific duration.

is_backup_access_code_availableBooleanIndicates whether a backup access code is available for use if the primary access code is lost or compromised.
is_backupBooleanIndicates whether the access code is a backup access code.
pulled_backup_access_code_idString (UUID)Identifier of the pulled backup access code. Used to associate the pulled backup access code with the original access code.
is_waiting_for_code_assignmentBooleanIndicates whether the access code is waiting for a code assignment.
is_external_modification_allowedBooleanIndicates whether changes to the access code from external sources are permitted.
is_one_time_useBooleanIndicates whether the access code can only be used once. If true, the code becomes invalid after the first use.
is_offline_access_codeBooleanIndicates whether the access code is intended for use in offline scenarios. If true, this code can be created on a device without a network connection.
starts_atDatetime (ISO 8601)Date and time at which the time-bound access code becomes active (only relevant for time_bound codes).
ends_atDatetime (ISO 8601)Date and time after which the time-bound access code becomes inactive (only relevant for time_bound codes).
created_atDatetime (ISO 8601)Date and time at which the access code was created.
errorsSee Access Code Error Types.

Collection of errors associated with the access code, structured in a dictionary format.

A unique error_code keys each error. Each error entry is an object containing two fields: message and created_at.

message is a string that describes the error.

created_at is a date that indicates when the error was generated.

This structure enables detailed tracking and timely response to critical issues.

warningsSee Access Code Warning Types.

Collection of warnings associated with the access code, structured in a dictionary format.

A unique warning_code keys each warning. Each warning entry is an object containing two fields: message and created_at.

message is a string that describes the warning.

created_at is a date that indicates when the warning was generated.

This structure enables detailed tracking and timely response to potential issues that are not critical but that may require attention.

@@ -110,6 +110,15 @@ Warnings are returned in a list: | `delay_in_setting_on_device` | There was an unusually long delay in programming the code onto the device. For time bound codes, this is sent when the code enters its active time. Note that this is a temporary warning and might be removed if the code is successfully set. | | `code_modified_external_to_seam` | When we detect that a code was modified or removed externally after Seam successfully set it on the device, and the `allow_external_modification` flag is set for the code, we will set this warning instead of an error. | -#### List of Methods - -
Create an Access CodeCreate an Access Code
Create many Access CodesCreate many Access Codes
Update an Access CodeUpdate an Access Code
Delete an Access CodeDelete an Access Code
Retrieve an Access CodeRetrieve an Access Code
Retrieve a list of Access CodesRetrieve a list of Access Codes
+## `access_code` Methods + +* [Create an access code](create-an-access-code.md) +* [Create many access codes](create-many-access-codes.md) +* [List access codes](list-access-codes.md) +* [Get an access code](get-an-access-code.md) +* [Update an access code](update-an-access-code.md) +* [Delete an access code](delete-an-access-code.md) +* [List unmanaged access codes](list-unmanaged-access-codes.md) +* [Convert an unmanaged access code](convert-an-unmanaged-access-code.md) +* [Delete an unmanaged access code](delete-an-unmanaged-access-code.md) +* [Pull a backup access code](pull-backup-access-code.md) diff --git a/docs/api-clients/events/README.md b/docs/api-clients/events/README.md index 3a3c7f00..e4c51c65 100644 --- a/docs/api-clients/events/README.md +++ b/docs/api-clients/events/README.md @@ -85,7 +85,7 @@ Noise sensors emit an event whenever a predefined noise threshold has been excee | Event Name | Description | | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `access_code.created` | An `access_code` has been created. | -| `access_code.changed` | An `access_code` status or property has changed. | +| `access_code.changed` | An `access_code` [status](../access-codes/#access\_code-properties) has changed. | | `access_code.scheduled_on_device` | For native scheduled codes (see [Native Scheduling](../../products/smart-locks/access-codes/#native-scheduling)), this event is sent when an `access_code` has been pre-programmed onto a device. An `access_code.set_on_device` is sent when the code is actually active. | | `access_code.set_on_device` | An `access_code` has been programmed onto a device. | | `access_code.backup_access_code_pulled` | A backup `access_code` has been pulled. |