Locking and Unlocking

Learn how to lock and unlock a smart lock, and confirm the action's success.

Overview

Seam enables you to lock or unlock your door lock remotely. This guide walks you through how to perform these actions using the Seam API.

When you send a command to a smart lock, it might take a while for Seam to confirm the action's success. To handle this, Seam provides an "action attempt" object, which indicates whether the action was successful.

To ensure that the action has been successfully executed, we advise checking the status of the action attempt object by polling the "Get Action Attempt" request. Once Seam has successfully confirmed the action, the action attempt's status will indicate success.

For those who prefer using webhooks to verify the success of an action, we'll soon introduce events that confirm an action's success.

---

Before You Begin: Confirm Capabilities

Before you attempt to lock or unlock a device, 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:

• can_remotely_lock

• can_remotely_unlock

Use Get Device (or Get Lock) 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 lock or unlock the device.

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 device.properties.online. In addition, you could look for a device.disconnected event.

Python

Request:

seam.locks.get(device="11111111-1111-1111-1111-444444444444")

Response:

Device(
  device_id='11111111-1111-1111-1111-444444444444',
  can_remotely_lock=True,   // You can use seam.locks.lock_door() on this device.
  can_remotely_unlock=True, // You can use seam.locks.unlock_door() on this device.
  ...
)

cURL (bash)

Request:

# Use GET or POST.
curl -X 'GET' \
  'https://connect.getseam.com/locks/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_remotely_lock": true,   // You can use /locks/lock_door on this device.
    "can_remotely_unlock": true, // You can use /locks/unlock_door on this device.
    ...
  },
  "ok": true
}

JavaScript

Request:

await seam.locks.get("11111111-1111-1111-1111-444444444444")

Response:

{
  device_id: '11111111-1111-1111-1111-444444444444',
  can_remotely_lock: true,   // You can use seam.locks.lockDoor() on this device.
  can_remotely_unlock: true, // You can use seam.locks.unlockDoor() on this device.
  ...
}

Ruby

Request:

client.locks.get("11111111-1111-1111-1111-444444444444")

Response:

<
  Seam::Device:0x00438
    device_id="11111111-1111-1111-1111-444444444444"
    can_remotely_lock=true   // You can use client.locks.lock_door() on this device.
    can_remotely_unlock=true // You can use client.locks.unlock_door() on this device.
    ...
>

PHP

Request:

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

Response:

{
  "device_id": "11111111-1111-1111-1111-444444444444",
  "can_remotely_lock": true,   // You can use $seam->locks->lock_door() on this device.
  "can_remotely_unlock": true, // You can use $seam->locks->unlock_door() on this device.
  ...
}

C#

Request:

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

Response:

{
  "device_id": "11111111-1111-1111-1111-444444444444",
  "can_remotely_lock": true,   // You can use seam.Locks.LockDoor() on this device.
  "can_remotely_unlock": true, // You can use seam.Locks.UnlockDoor() on this device.
  ...
}

Java

Request:

seam.locks()
  .get(LocksGetRequest.builder()
    .deviceId("11111111-1111-1111-1111-444444444444")
    .build());

Response:

{
  "device_id": "11111111-1111-1111-1111-444444444444",
  "can_remotely_lock": true,   // You can use seam.locks.lockDoor() on this device.
  "can_remotely_unlock": true, // You can use seam.locks.unlockDoor() on this device.
  ...
}

Go

Request:

device, uErr := client.Devices.Get(
  context.Background(),
  &api.DevicesGetRequest{
    DeviceId: "11111111-1111-1111-1111-444444444444",
  })

Response:

{
  "device_id": "11111111-1111-1111-1111-444444444444",
  "can_remotely_lock": true,   // You can use client.Locks.LockDoor() on this device.
  "can_remotely_unlock": true, // You can use client.Locks.UnlockDoor() on this device.
  ...
}

---

Locking a Door

You can lock a door using the lock_door endpoint. To confirm the success of the action, see Verifying the success of a lock or unlock action.

Python

Request:

# Get the device.
device = seam.locks.get(
  device_id="11111111-1111-1111-1111-444444444444"
)

# Confirm that the device can remotely lock.
if device.can_remotely_lock:
  # Perform the lock operation.
  seam.locks.lock_door(device_id=device.device_id)

Response:

ActionAttempt(status='pending',
              action_type='LOCK_DOOR',
              action_attempt_id='11111111-2222-3333-4444-555555555555',
              result=None,
              error={})

cURL (bash)

Request:

# 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 can remotely lock.
if  $(jq -r '.device.can_remotely_lock' <<< ${device}); then \
  # Perform the lock operation.
  curl -X 'POST' \
    'https://connect.getseam.com/locks/lock_door' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{
      \"device_id\": \"$(jq -r '.device.device_id' <<< ${device})\"
  }';
fi

Response:

{
  "action_attempt": {
    "status":"pending",
    "action_type":"LOCK_DOOR",
    "action_attempt_id":"11111111-2222-3333-4444-555555555555",
    "result":null,
    "error":null
  },
  "ok":true
}

JavaScript

Request:

// Get the device.
const device = await seam.locks.get({
  device_id: "11111111-1111-1111-1111-444444444444"
});

// Confirm that the device can remotely lock.
if (device.can_remotely_lock) {
  // Perform the lock operation.
  await seam.locks.lockDoor({
    device_id: device.device_id,
    waitForActionAttempt: true
  })
};

Response:

{
  actionAttempt: {
    status: 'success',
    action_attempt_id: '11111111-2222-3333-4444-555555555555',
    action_type: 'LOCK_DOOR',
    result: {},
    error: null
  }
}

Ruby

Request:

# Get the device.
device = client.locks.get("11111111-1111-1111-1111-444444444444")

# Confirm that the device can remotely lock.
if (device.can_remotely_lock)
  # Perform the lock operation.
  client.locks.lock_door(device.device_id)
end

Response:

<Seam::ActionAttempt:0x00438
  status="pending"
  action_type="LOCK_DOOR"
  action_attempt_id="11111111-2222-3333-4444-555555555555"
  result=nil>

PHP

Request:

// Get the device.
$device = $seam->locks->get(device_id: "11111111-1111-1111-1111-444444444444");

// Confirm that the device can remotely lock.
if ($device->can_remotely_lock) {
  // Perform the lock operation.
  $seam->locks->lock_door(device_id: $device->device_id);
}

Response:

{
  "action_attempt_id":"11111111-2222-3333-4444-555555555555",
  "action_type":"LOCK_DOOR",
  "error":null,
  "result":{},
  "status":"success"
}

C#

Request:

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

// Confirm that the device can remotely lock.
if (device.CanRemotelyLock == true) {
  // Perform the lock operation.
  seam.Locks.LockDoor(deviceId: device.DeviceId);
}

Response:

{
  "status": "pending",
  "action_type": "LOCK_DOOR",
  "action_attempt_id": "11111111-2222-3333-4444-555555555555"
}

Java

Request:

// Get the device.
Device device = seam.devices()
  .get(DevicesGetRequest.builder()
    .deviceId("11111111-1111-1111-1111-444444444444")
    .build());

// Confirm that the device can remotely lock.
if (device.getCanRemotelyLock())
{
  // Perform the lock operation.
  seam.locks()
    .lockDoor(LocksLockDoorRequest.builder()
      .deviceId(device.getDeviceId())
      .build());
}

Response:

Optional[
  {
    "action_type" : "LOCK_DOOR",
    "action_attempt_id" : "11111111-2222-3333-4444-555555555555",
    "status" : "pending"
  }
]

Go

Request:

// Get the device.
device, uErr := client.Locks.Get(
  context.Background(),
  &api.LocksGetRequest{
    DeviceId: api.String("11111111-1111-1111-1111-444444444444"),
  })

// Confirm that the device can remotely lock.
if *device.CanRemotelyLock {
  // Perform the lock operation.
  client.Locks.LockDoor(
      context.Background(),
      &api.LocksLockDoorRequest{
        DeviceId: device.DeviceId,
      },
    )
  }

if uErr != nil {
    return uErr
}

return nil

Response:

&{pending <nil>
  {
    "status": "pending",
    "action_type": "LOCK_DOOR",
    "action_attempt_id": "11111111-2222-3333-4444-555555555555",
    "result": null,
    "error": null
  }
<nil>} <nil>

---

Unlocking a Door

You can lock a door using the unlock_door endpoint. To confirm the success of the action, see Verifying the success of a lock or unlock action.

Python

Request:

# Get the device.
device = seam.locks.get(
  device_id="11111111-1111-1111-1111-444444444444"
)

# Confirm that the device can remotely unlock.
if device.can_remotely_unlock:
  # Perform the unlock operation.
  seam.locks.unlock_door(device_id=device.device_id)

Response:

ActionAttempt(status='pending',
              action_type='UNLOCK_DOOR',
              action_attempt_id='11111111-2222-3333-4444-555555555555',
              result=None,
              error={})

cURL (bash)

Request:

# 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 can remotely unlock.
if  $(jq -r '.device.can_remotely_lock' <<< ${device}); then \
  # Perform the unlock operation.
  curl -X 'POST' \
    'https://connect.getseam.com/locks/unlock_door' \
    -H 'accept: application/json' \
    -H "Authorization: Bearer ${API_KEY}" \
    -H 'Content-Type: application/json' \
    -d "{
      \"device_id\": \"$(jq -r '.device.device_id' <<< ${device})\"
  }";
fi

Response:

{
  "action_attempt": {
    "status":"pending",
    "action_type":"UNLOCK_DOOR",
    "action_attempt_id":"11111111-2222-3333-4444-555555555555",
    "result":null,
    "error":null
  },
  "ok":true
}

JavaScript

Request:

// Get the device.
const device = await seam.locks.get({
  device_id: "11111111-1111-1111-1111-444444444444"
});

// Confirm that the device can remotely unlock.
if (device.can_remotely_unlock) {
  // Perform the unlock operation.
  await seam.locks.unlockDoor({
    device_id: device.device_id,
    waitForActionAttempt: true
  })
};

Response:

{
  actionAttempt: {
    status: 'success',
    action_attempt_id: '11111111-2222-3333-4444-555555555555',
    action_type: 'UNLOCK_DOOR',
    result: {},
    error: null
  }
}

Ruby

Request:

# Get the device.
device = client.locks.get("11111111-1111-1111-1111-444444444444")

# Confirm that the device can remotely unlock.
if (device.can_remotely_unlock)
  # Perform the unlock operation.
  client.locks.unlock_door(device.device_id)
end

Response:

<Seam::ActionAttempt:0x00438
  status="pending"
  action_type="UNLOCK_DOOR"
  action_attempt_id="11111111-2222-3333-4444-555555555555"
  result=nil>

PHP

Request:

// Get the device.
$device = $seam->locks->get(device_id: "11111111-1111-1111-1111-444444444444");

// Confirm that the device can remotely unlock.
if ($device->can_remotely_unlock) {
  // Perform the unlock operation.
  $seam->locks->unlock_door(device_id: $device->device_id);
}

Response:

{
  "action_attempt_id":"11111111-2222-3333-4444-555555555555",
  "action_type":"UNLOCK_DOOR",
  "error":null,
  "result":{},
  "status":"success"
}

C#

Request:

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

// Confirm that the device can remotely unlock.
if (device.CanRemotelyUnlock == true) {
  // Perform the unlock operation.
  seam.Locks.UnlockDoor(deviceId: device.DeviceId);
}

Response:

{
  "status": "pending",
  "action_type": "UNLOCK_DOOR",
  "action_attempt_id": "11111111-2222-3333-4444-555555555555"
}

Java

Request:

// Get the device.
Device device = seam.devices()
  .get(DevicesGetRequest.builder()
    .deviceId("11111111-1111-1111-1111-444444444444")
    .build());

// Confirm that the device can remotely unlock.
if (device.getCanRemotelyUnlock())
{
  // Perform the unlock operation.
  seam.locks()
    .lockDoor(LocksUnlockDoorRequest.builder()
      .deviceId(device.getDeviceId())
      .build());
}

Response:

Optional[
  {
    "action_type" : "UNLOCK_DOOR",
    "action_attempt_id" : "11111111-2222-3333-4444-555555555555",
    "status" : "pending"
  }
]

Go

Request:

// Get the device.
device, uErr := client.Locks.Get(
  context.Background(),
  &api.LocksGetRequest{
    DeviceId: api.String("11111111-1111-1111-1111-444444444444"),
  })

// Confirm that the device can remotely unlock.
if *device.CanRemotelyUnlock {
  // Perform the unlock operation.
  client.Locks.UnlockDoor(
      context.Background(),
      &api.LocksUnlockDoorRequest{
        DeviceId: device.DeviceId,
      },
    )
  }

if uErr != nil {
    return uErr
}

return nil

Response:

&{pending <nil>
  {
    "status": "pending",
    "action_type": "UNLOCK_DOOR",
    "action_attempt_id": "11111111-2222-3333-4444-555555555555",
    "result": null,
    "error": null
  }
<nil>} <nil>

---

Verifying the Success of a Lock or Unlock Action

1. Execute a Lock request (or other action)

When initiating a lock or unlock action, the Seam API returns an action attempt, which monitors the success or failure of the action.

Python

Request:

seam.locks.lock_door(device_id="11111111-1111-1111-1111-444444444444")

Response:

ActionAttempt(status='pending',
              action_type='LOCK_DOOR',
              action_attempt_id='11111111-2222-3333-4444-555555555555',
              result=None,
              error={})

cURL (bash)

Request:

curl -X 'POST' \
  'https://connect.getseam.com/locks/lock_door' \
  -H 'accept: application/json' \
  -H "Authorization: Bearer ${API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "device_id": "11111111-1111-1111-1111-444444444444"
}'

Response:

{
  "action_attempt": {
    "status":"pending",
    "action_type":"LOCK_DOOR",
    "action_attempt_id":"11111111-2222-3333-4444-555555555555",
    "result":null,
    "error":null
  },
  "ok":true
}

JavaScript

Request:

await seam.locks.lockDoor({
  device_id: "11111111-1111-1111-1111-444444444444",
  waitForActionAttempt: true
});

Response:

{
  actionAttempt: {
    status: 'success',
    action_attempt_id: '11111111-2222-3333-4444-555555555555',
    action_type: 'LOCK_DOOR',
    result: {},
    error: null
  }
}

Ruby

Request:

client.locks.lock_door("11111111-1111-1111-1111-444444444444")

Response:

<Seam::ActionAttempt:0x00438
  status="pending"
  action_type="LOCK_DOOR"
  action_attempt_id="11111111-2222-3333-4444-555555555555"
  result=nil>

PHP

Request:

$seam->locks->lock_door(device_id: "11111111-1111-1111-1111-444444444444");

Response:

{
  "action_attempt_id":"11111111-2222-3333-4444-555555555555",
  "action_type":"LOCK_DOOR",
  "error":null,
  "result":{},
  "status":"success"
}

C#

Request:

seam.Locks.LockDoor(deviceId: "11111111-1111-1111-1111-444444444444");

Response:

{
  "status": "pending",
  "action_type": "LOCK_DOOR",
  "action_attempt_id": "11111111-2222-3333-4444-555555555555"
}

Java

Request:

seam.locks().lockDoor(LocksLockDoorRequest.builder()
  .deviceId("11111111-1111-1111-1111-444444444444")
  .build());

Response:

Optional[
  {
    "action_type" : "LOCK_DOOR",
    "action_attempt_id" : "11111111-2222-3333-4444-555555555555",
    "status" : "pending"
  }
]

Go

Request:

_, uErr := client.Locks.LockDoor(
  context.Background(),
  &api.LocksLockDoorRequest{
    DeviceId: "11111111-1111-1111-1111-444444444444",
  },
)

if uErr != nil {
    return uErr
}

return nil

Response:

&{pending <nil>
  {
    "status": "pending",
    "action_type": "LOCK_DOOR",
    "action_attempt_id": "11111111-2222-3333-4444-555555555555",
    "result": null,
    "error": null
  }
<nil>} <nil>

2. Poll the Action Attempt to Verify the Success of the Action

Use the action_attempt_id from the prior response to make a Get Action Attempt request. When the action attempt's status changes to success, it indicates the action has been successful.

Python

Request:

seam.action_attempts.get(action_attempt_id="11111111-2222-3333-4444-555555555555")

Response:

ActionAttempt(action_attempt_id='11111111-2222-3333-4444-555555555555',
              action_type='LOCK_DOOR',
              status='success',
              result={},
              error=None)

cURL (bash)

Request:

# Use GET or POST.
curl -X 'GET' \
  'https://connect.getseam.com/action_attempts/get' \
  -H 'accept: application/json' \
  -H "Authorization: Bearer ${API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
  "action_attempt_id": "11111111-2222-3333-4444-555555555555"
}'

Response:

{
  "action_attempt": {
    "status": "success",
    "action_attempt_id": "11111111-2222-3333-4444-555555555555",
    "action_type": "LOCK_DOOR",
    "result": {},
    "error": null
  },
  "ok": true
}

JavaScript

Request:

await seam.actionAttempts.get({action_attempt_id: "11111111-2222-3333-4444-555555555555"});

Response:

{
  status: 'success',
  action_attempt_id: '11111111-2222-3333-4444-555555555555',
  action_type: 'LOCK_DOOR',
  result: {},
  error: null
}

Ruby

Request:

client.action_attempts.get("11111111-2222-3333-4444-555555555555")

Response:

<Seam::ActionAttempt:0x00438
  status="success"
  action_attempt_id="11111111-2222-3333-4444-555555555555"
  action_type="LOCK_DOOR"
  result={}>

PHP

Request:

$seam->action_attempts->get(action_attempt_id: "11111111-2222-3333-4444-555555555555");

Response:

{
  "action_attempt_id":"11111111-2222-3333-4444-555555555555",
  "action_type":"LOCK_DOOR",
  "error":null,
  "result":{},
  "status":"success"
}

C#

Request:

seam.ActionAttempts.Get("11111111-2222-3333-4444-555555555555");

Response:

{
  "status": "success",
  "action_type": "LOCK_DOOR",
  "action_attempt_id": "11111111-2222-3333-4444-555555555555",
  "result": {},
  "error": null
}

Java

Request:

seam.actionAttempts().get(ActionAttemptsGetRequest.builder()
  .actionAttemptId("11111111-2222-3333-4444-555555555555")
  .build());

Response:

Optional[
  {
    "action_type" : "LOCK_DOOR",
    "action_attempt_id" : "11111111-2222-3333-4444-555555555555",
    "status" : "success",
    "result": {},
    "error": null
  }
]

Go

Request:

action_attempt, uErr := client.ActionAttempts.Get(context.Background(), &api.ActionAttemptsGetRequest{
  ActionAttemptId: "11111111-2222-3333-4444-555555555555",
})

if uErr != nil {
return uErr
}

return nil

Response:

&{success
  {
    "status": "success",
    "action_attempt_id": "11111111-2222-3333-4444-555555555555",
    "action_type": "LOCK_DOOR",
    "result": {},
    "error": null
  }
<nil> <nil>}

---

Checking the Locked Status of a Lock

To retrieve the locked status of a specific door lock, use the Get Lock or Get Device endpoint by providing the device_id of the desired lock. This operation returns detailed information, including the current locked status.

Python

Request:

seam.locks.get(device="11111111-1111-1111-1111-444444444444")

Response:

Device(
  device_id='11111111-1111-1111-1111-444444444444',
  properties={
    'locked': True,
    ...
  },
  ...
)

cURL (bash)

Request:

# Use GET or POST.
curl -X 'GET' \
  'https://connect.getseam.com/locks/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",
    "properties": {
      "locked": true,
      ...
    },
    ...
  },
  "ok": true
}

JavaScript

Request:

await seam.locks.get("11111111-1111-1111-1111-444444444444")

Response:

{
  device_id: '11111111-1111-1111-1111-444444444444',
  properties: {
    locked: true,
    ...
  },
  ...
}

Ruby

Request:

client.locks.get("11111111-1111-1111-1111-444444444444")

Response:

<Seam::Device:0x00438
  device_id="11111111-1111-1111-1111-444444444444"
  properties={
    "locked"=>true,
    ...
  }
  ...
>

PHP

Request:

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

Response:

{
  "device_id": "11111111-1111-1111-1111-444444444444",
  "properties": {
    "locked": true,
    ...
  },
  ...
}

C#

Request:

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

Response:

{
  "device_id": "11111111-1111-1111-1111-444444444444",
  "properties": {
    "locked": true,
    ...
  },
  ...
}

Java

Request:

seam.locks().get(LocksGetRequest.builder()
  .deviceId("11111111-1111-1111-1111-444444444444")
  .build());

Response:

{
  "device_id" : "11111111-1111-1111-1111-444444444444",
  "properties" : {
    "locked" : true,
    ...
  },
  ...
}

Go

Request:

device, uErr := client.Devices.Get(
  context.Background(),
  &api.DevicesGetRequest{
    DeviceId: "11111111-1111-1111-1111-444444444444",
  })

Response:

{
  "device_id": "11111111-1111-1111-1111-444444444444",
  "properties" : {
    "locked" : true,
    ...
  },
  ...
}

---

Lock and Unlock Events

Whenever a lock is locked or unlocked, Seam emits a lock.locked or lock.unlocked event. You can see these events by making a List Events request or by setting up a webhook. For more information on how to set up webhooks, see the Webhooks guide.

A lock or unlock event looks like the following:

{
  "event": {
    "event_id": "22222222-3333-4444-5555-666666666666",
    "device_id": "11111111-1111-1111-1111-444444444444",
    "event_type": "lock.locked",
    "workspace_id": "00000000-0000-0000-0000-000000000000",
    "created_at": "2023-10-13T15:10:18.443Z",
    "occurred_at": "2023-10-13T15:09:08.531Z",
    "method": "unknown",
    "connected_account_id": "11111111-1111-1111-1111-222222222222"
  },
  "ok": true
}

For more information about the lock.locked and lock.unlocked attributes, please see Events.