This guide explains how to create online access codes on an online smart lock. With the API, generate PIN codes on a door lock and share it with visitors, allowing them keyless access.
Seam supports programming two types of online access codes for online door locks:
Ongoing: Ideal for residents or long-term users. Ongoing codes remain active on a device until removed. Create one by omitting both starts_at and ends_at. To remove the code, use the endpoint.
Time Bound: Suitable for temporary access like guest visits or service appointments. These codes operate between a designated starts_at and ends_at time window, granting access only during that period.
For more information about creating offline access codes, see .
Before You Begin: Confirm Capabilities
Before you attempt to create an or access code, be sure to confirm that your device has the capability to perform these operations. You can inspect the capabilities of a device by checking the following for the device:
device.can_program_online_access_codes
device.can_program_offline_access_codes
Use (or ) for a specific device to return these capability flags. Then, use an if statement or similar check to confirm that the relevant flag is both present and true before attempting to create an access code.
If either of these capability flags is false or not present, you can view the of the device, or for the device, and related to the device to learn more about the cause of these issues. For example, you could examine the following device properties:
Device(
device_id='11111111-1111-1111-1111-444444444444',
can_program_online_access_codes=True, // You can create online access codes for this device.
can_program_offline_access_codes=True, // You can create offline access codes for this device.
...
)
Request:
# Use GET or POST.
curl -X 'GET' \
'https://connect.getseam.com/devices/get' \
-H 'accept: application/json' \
-H 'Authorization: Bearer ${API_KEY}' \
-H 'Content-Type: application/json' \
-d '{
"device_id": "11111111-1111-1111-1111-444444444444"
}'
Response:
{
"lock": {
"device_id": "11111111-1111-1111-1111-444444444444",
"can_program_online_access_codes": true, // You can create online access codes for this device.
"can_program_offline_access_codes": true, // You can create offline access codes for this device.
...
},
"ok": true
}
{
device_id: '11111111-1111-1111-1111-444444444444',
can_program_online_access_codes: true, // You can create online access codes for this device.
can_program_offline_access_codes: true, // You can create offline access codes for this device.
...
}
<Seam::Device:0x00438
device_id="11111111-1111-1111-1111-444444444444"
can_program_online_access_codes=true // You can create online access codes for this device.
can_program_offline_access_codes=true // You can create offline access codes for this device.
...
>
{
"device_id": "11111111-1111-1111-1111-444444444444",
"can_program_online_access_codes": true, // You can create online access codes for this device.
"can_program_offline_access_codes": true, // You can create offline access codes for this device.
...
}
{
"device_id": "11111111-1111-1111-1111-444444444444",
"can_program_online_access_codes": true, // You can create online access codes for this device.
"can_program_offline_access_codes": true, // You can create offline access codes for this device.
...
}
{
"device_id": "11111111-1111-1111-1111-444444444444",
"can_program_online_access_codes": true, // You can create online access codes for this device.
"can_program_offline_access_codes": true, // You can create offline access codes for this device.
...
}
{
"device_id": "11111111-1111-1111-1111-444444444444",
"can_program_online_access_codes": true, // You can create online access codes for this device.
"can_program_offline_access_codes": true, // You can create offline access codes for this device.
...
}
Programming an Ongoing Online Access Code
Ongoing online access codes are ideal for long-term users that wish to keep the same code. Ongoing codes remain active on a device until removed.
1. Create an Ongoing Online Access Code
Request:
# Get the device.
device = seam.devices.get(
device_id="11111111-1111-1111-1111-444444444444"
)
# Confirm that the device supports online access codes.
if device.can_program_online_access_codes:
# Create the ongoing online access code.
seam.access_codes.create(
device_id = device.device_id,
name = "my ongoing code",
code = "1234"
)
# Get the device.
device = client.devices.get(device_id: "11111111-1111-1111-1111-444444444444")
# Confirm that the device supports online access codes.
if (device.can_program_online_access_codes)
# Create the ongoing online access code.
client.access_codes.create(
device_id: device.device_id,
name: "my ongoing code",
code: "1234"
)
end
Seam may encounter some problems when setting an access code onto the lock. This could be due to weak internet connectivity, a low battery in the door lock, or someone unplugging the bridge that links the lock to the internet. Given these potential challenges, it's essential to verify that a code has been successfully programmed on to the lock to prevent unexpected complications later.
There are two methods to verify that an ongoing access code has been set on the device:
Polling: continuously query the access code until its status is updated
Webhook: wait for updates to arrive via webhook requests from the Seam API
Polling Method
Webhook Events Method
To avoid polling, monitor for incoming Seam webhook events related to the code status:
The access_code.set_on_device event indicates the successful setting of the access code on the device.
The access_code.failed_to_set_on_device or access_code.delay_in_setting_on_device events indicate a delay or failure.
Scheduling Time-Bound Online Access Codes
Time-bound online access codes are suitable for temporary access, like guest visits or service appointments. These codes operate between designated starts_at and ends_at timestamps, granting access only during that period. Seam automatically ensures that the code is programmed on the device at the starts_at time and unprogrammed at the ends_at time.
1. Create a Time-Bound Online Access Code
As with ongoing codes, you can assign an optional name to the access code. A clear name helps users to identify the access code quickly within their smart lock app.
Request:
# Get the device.
device = seam.devices.get(
device_id="11111111-1111-1111-1111-444444444444"
)
# Confirm that the device supports online access codes.
if device.can_program_online_access_codes:
# Create the time-bound online access code.
seam.access_codes.create(
device_id = device.device_id,
name = "my time-bound code",
starts_at = "2025-01-01T16:00:00Z",
ends_at = "2025-01-22T12:00:00Z",
code = "2345"
)
Unset: When initially created on Seam, the access code remains in an unset state, indicating it has not yet been programmed onto the door lock due to its future activation time.
Setting: As the scheduled starts_at time approaches, Seam initiates the process of programming the code onto the lock, transitioning the code's status to setting.
Set: Upon successful programming, the status updates to set, signaling that the code is loaded onto the lock, and may grant the designated user the ability to unlock the door.
There are two methods to verify that an time-bound access code has been set on the device:
Polling: continuously query the access code until its status is updated
Webhook: wait for updates to arrive via webhook requests from the Seam API
Polling Method
Webhook Events Method
To avoid polling, monitor for incoming Seam webhook events related to the code status:
The access_code.set_on_device event indicates the successful setting of the access code on the device.
The access_code.failed_to_set_on_device or access_code.delay_in_setting_on_device events indicate a delay or failure.
Set an ongoing online access code by providing the device_id of the smart lock on which you want to . Assign an optional name to the access code for easier identification within the and smart lock app.
To customize the PIN code, specify a desired PIN for the code property. If you do not specify a code, you can set the preferred_code_length, and Seam generates a code of this length if the affected device supports the specified preferred code length. See to understand any requirements specific to the door lock.
Use the access_code reference returned by the create function to call the function. A basic implementation would involve polling this endpoint until the status of the access code updates to set.
If the status remains setting for a very long time, or if the access_code object contains any warnings or errors properties, consult for further guidance.
In the event of delay or failure, refer to for assistance and mitigation strategies.
To set a time-bound online access code, provide the device_id of the smart lock on which you want to program a code, along with starts_at and ends_at timestamps to define the active time window for the code. For more details, see the endpoint.
Similarly, to customize the PIN code, specify a desired PIN in the code property. If you do not specify a code, you can set the preferred_code_length, and Seam generates a code of this length if the affected device supports the specified preferred code length. See the to understand any requirements specific to the door lock brand.
The is marked by distinct phases:
On door locks that support access codes, Seam will preload the access code into the device's internal memory bank 72 hours ahead of the starts_at time. Even if preloaded in memory, the access code will remain in an unset state ahead of the starts_at time and await the precise activation moment to toggle its status. When the starts_at time arrives, the access code becomes active and transition to a set status, granting the designated user the ability to utilize it for entry. If there's an issue programming the natively-scheduled code by its starts_at time, the code's status will display as setting. For more information on the lifecycle of access codes, .
Use the access_code reference returned by the create function to call the function. In a basic implementation, you would poll this endpoint at the starts_at time to check if the access code's status is updated to set.
If the status remains setting, or if the access_code object displays any warnings or errors, refer to for assistance.
In the event of delay or failure, refer to for assistance and mitigation strategies.
