Creating Access Codes

This is a low-level API. For granting a person access, use Access Grants—the default and recommended way to grant access to any physical space, across both standalone smart locks and access systems. We don’t recommend building on the Access Codes API directly unless you specifically need low-level control over individual PIN codes (or have discussed your use case with the Seam team at support@seam.co).

Overview

This guide explains how to create online access codes on an online smart lock. With the Access Codes 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 Delete Access Code 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 Managing Offline Access Codes.

Before You Begin: Confirm Capabilities

Before you attempt to create an online or offline 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 capability flags for the device:

device.can_program_online_access_codes
device.can_program_offline_access_codes

Use Get Device 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 properties of the device, errors or warnings for the device, and events related to the device to learn more about the cause of these issues. For example, you could examine the following device properties:

device.properties.model.has_built_in_keypad
device.properties.model.can_connect_accessory_keypad
device.properties.accessory_keypad.is_connected
device.properties.accessory_keypad.battery.level

In addition, you could look for a device.accessory_keypad_disconnected event. Request:

await seam.devices.get({ device_id: '11111111-1111-1111-1111-444444444444' })

# 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"
}'

seam.devices.get(device_id="11111111-1111-1111-1111-444444444444")

client.devices.get(device_id: "11111111-1111-1111-1111-444444444444")

$seam->devices->get(device_id: "11111111-1111-1111-1111-444444444444");

seam.Devices.Get(deviceId: "11111111-1111-1111-1111-444444444444");

Response:

{
  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.
  ...
}

{
  "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(
  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.
  ...
}

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.

Timeline of an ongoing access code. The code remains active, until you use
the Seam API to remove it.

1. Create an Ongoing Online Access Code

Set an ongoing online access code by providing the device_id of the smart lock on which you want to create an access code. Assign an optional name to the access code for easier identification within the Seam Console 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 Access Code Requirements for Door Locks to understand any requirements specific to the door lock. Request:

// Get the device.
const device = await 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.
  await seam.accessCodes.create({
    device_id: device.device_id,
    name: 'my ongoing code',
    code: '1234',
  })
}

# Get the device.
device=$(
  # 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"
  }')

# Confirm that the device supports online access codes.
if  $(jq -r '.device.can_program_online_access_codes' <<< ${device}); then \
  # Create the ongoing online access code.
  curl -X 'POST' \
    'https://connect.getseam.com/access_codes/create' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{
      \"device_id\": \"$(jq -r '.device.device_id' <<< ${device})\",
      \"name\": \"my ongoing code\",
      \"code\": \"1234\"
  }";
fi

# 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

// 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 device = seam.Devices.Get(deviceId: "11111111-1111-1111-1111-444444444444");

// Confirm that the device supports online access codes.
if (device.CanProgramOnlineAccessCodes == true) {
  // Create the ongoing online access code.
  seam.AccessCodes.Create(
    deviceId: device.DeviceId,
    name: "my ongoing code",
    code: "1234"
  );
}

Response:

{
  access_code_id: '11111111-1111-1111-1111-555555555555',
  device_id: '11111111-1111-1111-1111-444444444444',
  name: 'my ongoing code',
  code: '1234',
  type: 'ongoing',
  ...
}

{
  "action_attempt":{
    "status":"pending",
    "action_type":"CREATE_ACCESS_CODE",
    "action_attempt_id":"11111111-2222-3333-4444-555555555555",
    "result":null,
    "error":null
  },
  "access_code":{
    "access_code_id":"11111111-1111-1111-1111-555555555555",
    "device_id":"11111111-1111-1111-1111-444444444444",
    "name":"my ongoing code",
    "code":"1234",
    "type":"ongoing",
    ...
  },
  "ok":true
}

AccessCode(
  access_code_id='11111111-1111-1111-1111-555555555555',
  device_id='11111111-1111-1111-1111-444444444444',
  type='ongoing',
  code='1234',
  name='my ongoing code',
  ...
)

<Seam::AccessCode:0x00460
  access_code_id="11111111-1111-1111-1111-555555555555"
  device_id="11111111-1111-1111-1111-444444444444"
  name="my ongoing code"
  code="1234"
  type="ongoing"
  ...
>

{
  "access_code_id": "11111111-1111-1111-1111-555555555555",
  "device_id": "11111111-1111-1111-1111-444444444444",
  "name": "my ongoing code",
  "type": "ongoing",
  "code": "1234",
  ...
}

{
  "type": "ongoing",
  "access_code_id": "11111111-1111-1111-1111-555555555555",
  "device_id": "11111111-1111-1111-1111-444444444444",
  "name": "my ongoing code",
  "code": "1234",
  ...
}

2. Verify Successful Ongoing Code Programming

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 pending_mutations list is empty
Webhook: wait for updates to arrive via webhook requests from the Seam API

Polling Method

Use the access_code reference returned by the create function to call the Get Access Code function. A basic implementation would involve polling this endpoint until the access code’s pending_mutations list no longer contains a creating mutation, which indicates that the code was programmed onto the device. If the creating pending mutation remains for a very long time, or if the access_code object contains any warnings or errors properties, consult the guide on “Troubleshooting Access Code Issues” for further guidance.

Illustration of the polling verification step for an ongoing access code

Webhook Events Method

To avoid polling, monitor for incoming Seam webhook events related to the code status:

The access_code.issued event indicates that the access code was successfully programmed and will work for its desired time frame.
The access_code.delay_in_issuing or access_code.failed_to_issue events indicate a delay or failure. See Lifecycle Events for the recommended actions to take.

In the event of delay or failure, refer to the “Troubleshooting access code issues” guide for assistance and mitigation strategies.

Illustration of the webhook verification method for an ongoing access code

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.

Timeline of an time-bound access code. The code remains active until the
ends_at timestamp that you configured using the Seam API.

1. Create a Time-Bound Online Access Code

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 ISO 8601 timestamps to define the active time window for the code. For more details, see the Create Access Code endpoint. 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. 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 Access Code Requirements for Door Locks to understand any requirements specific to the door lock brand. Request:

// Get the device.
const device = await 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.
  await seam.accessCodes.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',
  })
}

# Get the device.
device=$(
  # 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"
  }')

# Confirm that the device supports online access codes.
if  $(jq -r '.device.can_program_online_access_codes' <<< ${device}); then \
  # Create the time-bound online access code.
  curl -X 'POST' \
    'https://connect.getseam.com/access_codes/create' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{
      \"device_id\": \"$(jq -r '.device.device_id' <<< ${device})\",
      \"name\": \"my time-bound code\",
      \"starts_at\": \"2025-01-01T16:00:00Z\",
      \"ends_at\": \"2025-01-22T12:00:00Z\",
      \"code\": \"2345\"
  }";
fi

# 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"
  )

# 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 time-bound online access code.
  client.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"
  )
end

// 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"
  );
}

// Get the device.
Device device = seam.Devices.Get(deviceId: "11111111-1111-1111-1111-444444444444");

// Confirm that the device supports online access codes.
if (device.CanProgramOnlineAccessCodes == true) {
  // Create the time-bound online access code.
  seam.AccessCodes.Create(
    deviceId: device.DeviceId,
    name: "my time-bound code",
    startsAt: "2025-01-01T16:00:00Z",
    endsAt: "2025-01-22T12:00:00Z",
    code: "2345"
  );
}

Response:

{
  access_code_id: '11111111-1111-1111-1111-666666666666',
  device_id: '11111111-1111-1111-1111-444444444444',
  name: 'my time-bound code',
  code: '2345',
  type: 'time_bound',
  starts_at: '2025-01-01T16:00:00.000Z',
  ends_at: '2025-01-22T12:00:00.000Z',
  ...
}

{
  "action_attempt": {
    "status": "pending",
    "action_type": "CREATE_ACCESS_CODE",
    "action_attempt_id": "11111111-2222-3333-4444-555555555555",
    "result": null,
    "error": null
  },
  "access_code": {
    "access_code_id": "11111111-1111-1111-1111-666666666666",
    "device_id": "11111111-1111-1111-1111-444444444444",
    "name": "my time-bound code",
    "code": "2345",
    "type": "time_bound",
    "starts_at": "2025-01-01T16:00:00.000Z",
    "ends_at": "2025-01-22T12:00:00.000Z",
    ...
  },
  "ok": true
}

AccessCode(
  access_code_id='11111111-1111-1111-1111-666666666666',
  device_id='11111111-1111-1111-1111-444444444444',
  type='time_bound',
  code='2345',
  starts_at='2025-01-01T16:00:00.000Z',
  ends_at='2025-01-22T12:00:00.000Z',
  name='my time-bound code',
  ...
)

<Seam::AccessCode:0x00438
  access_code_id="11111111-1111-1111-1111-666666666666"
  device_id="11111111-1111-1111-1111-444444444444"
  name="my time-bound code"
  code="2345"
  type="time_bound"
  starts_at=2025-01-01 16:00:00 UTC
  ends_at=2025-01-22 12:00:00 UTC
  ...
>

{
  "access_code_id": "11111111-1111-1111-1111-666666666666",
  "device_id": "11111111-1111-1111-1111-444444444444",
  "name": "my time-bound code",
  "type": "time_bound",
  "starts_at": "2025-01-01T16:00:00.000Z",
  "ends_at": "2025-01-22T12:00:00.000Z",
  "code": "2345"
}

{
  "type": "time_bound",
  "access_code_id": "11111111-1111-1111-1111-666666666666",
  "device_id": "11111111-1111-1111-1111-444444444444",
  "name": "my time-bound code",
  "starts_at": "2025-01-01T16:00:00Z",
  "ends_at": "2025-01-22T12:00:00Z",
  "code": "2345",
  ...
}

2. Verify Successful Time-Bound Code Programming

The lifecycle of a time-bound access code is marked by distinct phases:

Waiting to issue: For natively-scheduled codes, Seam deliberately waits to program the code onto the lock until close to the starts_at time. The code carries a deferring_creation pending mutation while Seam is waiting.
Issuing: Seam programs the code onto the lock. The code carries a creating pending mutation while this work is in progress.
Upcoming: The code is on the lock but its starts_at time has not arrived yet. For natively-scheduled codes, Seam preloads the code ahead of the starts_at time; it waits on the device for its activation moment.
Active: The pending mutation clears and Seam emits the access_code.issued event, signaling that the code is loaded onto the lock and may grant the designated user the ability to unlock the door.

If there’s an issue programming the code, Seam reports it through the access_code.delay_in_issuing and access_code.failed_to_issue events and the matching warning and error on the access code. For more information on the lifecycle of access codes, please refer to this guide. 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 pending_mutations list is empty
Webhook: wait for updates to arrive via webhook requests from the Seam API

Polling Method

Use the access_code reference returned by the create function to call the Get Access Code function. In a basic implementation, you would poll this endpoint to check that the access code’s pending_mutations list no longer contains a creating or deferring_creation mutation, which indicates that the code was programmed onto the device. If a creating pending mutation remains as the starts_at time approaches, or if the access_code object displays any warnings or errors, refer to the “Troubleshooting Access Code Issues” guide for assistance.

Poll an access code to verify that it is ready for its scheduled access window

Webhook Events Method

To avoid polling, monitor for incoming Seam webhook events related to the code status:

The access_code.issued event indicates that the access code was successfully programmed and will work for its desired time frame.
The access_code.delay_in_issuing or access_code.failed_to_issue events indicate a delay or failure. See Lifecycle Events for the recommended actions to take.

In the event of delay or failure, refer to the “Troubleshooting access code issues” guide for assistance and mitigation strategies.

Getting Started

Use Cases

Core Concepts

Capability Guides

UI Components

Developer Tools

Industry Guides

Device Manufacturer Guidance

Low-Level APIs

Creating Access Codes

Overview

Before You Begin: Confirm Capabilities

Programming an Ongoing Online Access Code

1. Create an Ongoing Online Access Code

2. Verify Successful Ongoing Code Programming

Polling Method

Webhook Events Method

Scheduling Time-Bound Online Access Codes

1. Create a Time-Bound Online Access Code

2. Verify Successful Time-Bound Code Programming

Polling Method

Webhook Events Method

​Overview

​Before You Begin: Confirm Capabilities

​Programming an Ongoing Online Access Code

​1. Create an Ongoing Online Access Code

​2. Verify Successful Ongoing Code Programming

​Polling Method

​Webhook Events Method

​Scheduling Time-Bound Online Access Codes

​1. Create a Time-Bound Online Access Code

​2. Verify Successful Time-Bound Code Programming

​Polling Method

​Webhook Events Method

Overview

Before You Begin: Confirm Capabilities

Programming an Ongoing Online Access Code

1. Create an Ongoing Online Access Code

2. Verify Successful Ongoing Code Programming

Polling Method

Webhook Events Method

Scheduling Time-Bound Online Access Codes

1. Create a Time-Bound Online Access Code

2. Verify Successful Time-Bound Code Programming

Polling Method

Webhook Events Method